Skip to main content

module String

Usage

import String;

Synopsis

Library functions for strings.

Description

For operators on strings see String in the Rascal Language Reference.

The following functions are defined for strings:

function center

str center(str s, int n)

str center(str s, int n, str pad)

Synopsis

Center a string in given space.

Description

  • Center string s in string of length n using spaces.
  • Center string s in string of length n using pad as padding character.

Examples

rascal>import String;
ok
rascal>center("abc", 10);
str: " abc "
rascal>center("abc", 10, "x");
str: "xxxabcxxxx"

function charAt

int charAt(str s, int i) throws IndexOutOfBounds

Synopsis

Return character in a string by its index position.

Description

Return the character at position i in string s as integer character code. Also see stringChar that converts character codes back to string.

Examples

rascal>import String;
ok
rascal>charAt("abc", 0);
int: 97
rascal>stringChar(charAt("abc", 0));
str: "a"

function chars

list[int] chars(str s)

Synopsis

Return characters of a string.

Description

Return a list of the characters of s as integer character codes. Also see stringChars that converts character codes back to string.

Examples

rascal>import String;
ok
rascal>chars("abc");
list[int]: [97,98,99]
rascal>stringChars(chars("abc")) == "abc";
bool: true

function contains

bool contains(str input, str find)

Synopsis

Check that a string contains another string.

Description

Check whether the string find occurs as substring in the string subject.

Examples

rascal>import String;
ok
rascal>contains("abracadabra", "bra");
bool: true
rascal>contains("abracadabra", "e");
bool: false

function deescape

str deescape(str s)

Synopsis

Replace escaped characters by the escaped character itself (using Rascal escape conventions).

function endsWith

bool endsWith(str subject, str suffix)

Synopsis

Check whether a string ends with a given substring.

Description

Yields true if string subject ends with the string suffix.

Examples

rascal>import String;
ok
rascal>endsWith("Hello.rsc", ".rsc");
bool: true

function escape

str escape(str subject, map[str,str] mapping)

Synopsis

Replace single characters in a string.

Description

Return a copy of subject in which each single character key in replacements has been replaced by its associated value.

Examples

rascal>import String;
ok
rascal>import IO;
ok
rascal>escape("abracadabra", ("a" : "AA", "c" : "C"));
str: "AAbrAACAAdAAbrAA"
rascal>L = escape("\"Good Morning\", he said", ("\"": "\\\""));
str: "\\\"Good Morning\\\", he said"
rascal>println(L);
\"Good Morning\", he said
ok

function findAll

list[int] findAll(str subject, str find)

Synopsis

Find all occurrences of a string in another string.

Description

Find all occurrences of string find in string subject. The result is a (possible empty) list of positions where find matches.

See also find first and find last.

Examples

rascal>import String;
ok
rascal>findAll("abracadabra", "a");
list[int]: [0,3,5,7,10]
rascal>findAll("abracadabra", "bra");
list[int]: [1,8]
rascal>findAll("abracadabra", "e");
list[int]: []

function findFirst

int findFirst(str subject, str find)

Synopsis

Find the first occurrence of a string in another string.

Description

Find the first occurrence of string find in string subject. The result is either a position in subject or -1 when find is not found.

Also see find all and find last.

Examples

rascal>import String;
ok
rascal>findFirst("abracadabra", "a");
int: 0
rascal>findFirst("abracadabra", "bra");
int: 1
rascal>findFirst("abracadabra", "e");
int: -1

function findLast

int findLast(str subject, str find)

Synopsis

Find the last occurrence of a string in another string.

Description

Find the last occurrence of string find in string subject. The result is either a position in subject or -1 when find is not found.

Also see find all and find first.

Examples

rascal>import String;
ok
rascal>findLast("abracadabra", "a");
int: 10
rascal>findLast("abracadabra", "bra");
int: 8
rascal>findLast("abracadabra", "e");
int: -1

function isEmpty

bool isEmpty(str s)

Synopsis

Check whether a string is empty.

Description

Returns true if string s is empty.

Examples

rascal>import String;
ok
rascal>isEmpty("");
bool: true
rascal>isEmpty("abc");
bool: false

function arbString

str arbString(int n)

Synopsis

Generate a arbitrary string.

Description

Returns a string of maximum n length, with arbitrary characters.

Examples

rascal>import String;
ok
rascal>arbString(3);
str: "𒇇"
rascal>arbString(10);
str: "\a04¥¥\a05¬\a00§§¡¬«\'"

function left

str left(str s, int n)

str left(str s, int n, str pad)

Synopsis

Left alignment of string in given space.

Description

  • Left align string s in string of length n using spaces.
  • Left align string s in string of length n using pad as pad character.

Examples

rascal>import String;
ok
rascal>left("abc", 10);
str: "abc "
rascal>left("abc", 10, "x");
str: "abcxxxxxxx"

function replaceAll

str replaceAll(str subject, str find, str replacement)

Synopsis

Replace all occurrences of a string in another string.

Description

Return a copy of subject in which all occurrences of find (if any) have been replaced by replacement. Also see replace first and replace last.

Examples

rascal>import String;
ok
rascal>replaceAll("abracadabra", "a", "A");
str: "AbrAcAdAbrA"
rascal>replaceAll("abracadabra", "ra", "RARA");
str: "abRARAcadabRARA"
rascal>replaceAll("abracadabra", "cra", "CRA");
str: "abracadabra"

Pitfalls

Note that find is a string (as opposed to, for instance, a regular expression in Java).

function replaceFirst

str replaceFirst(str subject, str find, str replacement)

Synopsis

Replace the first occurrence of a string in another string.

Description

Return a copy of subject in which the first occurrence of find (if it exists) has been replaced by replacement. Also see replace all and replace last.

Examples

rascal>import String;
ok
rascal>replaceFirst("abracadabra", "a", "A");
str: "Abracadabra"
rascal>replaceFirst("abracadabra", "ra", "RARA");
str: "abRARAcadabra"
rascal>replaceFirst("abracadabra", "cra", "CRA");
str: "abracadabra"

Pitfalls

Note that find is a string (as opposed to, for instance, a regular expression in Java).

function replaceLast

str replaceLast(str subject, str find, str replacement)

Synopsis

Replace the last occurrence of a string in another string.

Description

Return a copy of subject in which the last occurrence of find (if it exists) has been replaced by replacement. Also see replace first and replace last.

Examples

rascal>import String;
ok
rascal>replaceLast("abracadabra", "a", "A");
str: "abracadabrA"
rascal>replaceLast("abracadabra", "ra", "RARA");
str: "abracadabRARA"
rascal>replaceLast("abracadabra", "cra", "CRA");
str: "abracadabra"

Pitfalls

Note that find is a string (as opposed to, for instance, a regular expression in Java).

function reverse

str reverse(str s)

Synopsis

Return a string with all characters in reverse order.

Description

Returns string with all characters of string s in reverse order.

Examples

rascal>import String;
ok
rascal>reverse("abc");
str: "cba"

function right

str right(str s, int n)

str right(str s, int n, str pad)

Synopsis

Right alignment of a string value in a given space.

Description

  • Right align string s in string of length n using spaces.
  • Right align string s in string of length n using pad as pad character.

Examples

rascal>import String;
ok
rascal>right("abc", 10);
str: " abc"
rascal>right("abc", 10, "x");
str: "xxxxxxxabc"

Synopsis

Right align s in string of length n using space.

Examples

rascal>import String;
ok
rascal>right("abc", 10);
str: " abc"
rascal>right("abc", 10, "x");
str: "xxxxxxxabc"

function size

int size(str s)

Synopsis

Determine length of a string value.

Description

Returns the length (number of characters) in string s.

Examples

rascal>import String;
ok
rascal>size("abc");
int: 3
rascal>size("");
int: 0

function startsWith

bool startsWith(str subject, str prefix)

Synopsis

Check whether a string starts with a given prefix.

Description

Yields true if string subject starts with the string prefix.

Examples

rascal>import String;
ok
rascal>startsWith("Hello.rsc", "Hell");
bool: true

function stringChar

str stringChar(int char) throws IllegalArgument

Synopsis

Convert a character code into a string.

function stringChars

str stringChars(list[int] chars) throws IllegalArgument

Synopsis

Convert a list of character codes into a string.

function isValidCharacter

bool isValidCharacter(int ch)

Synopsis

Check that a given integer value is a valid Unicode code point.

function substring

str substring(str s, int begin)

str substring(str s, int begin, int end)

Synopsis

Extract a substring from a string value.

Description

  • Yields substring of string s from index begin to the end of the string.
  • Yields substring of string s from index begin to (but not including) index end.

Examples

rascal>import String;
ok
rascal>substring("abcdef", 2);
str: "cdef"
rascal>substring("abcdef", 2, 4);
str: "cd"

function toInt

int toInt(str s) throws IllegalArgument

int toInt(str s, int r) throws IllegalArgument

Synopsis

Convert a string value to integer.

Description

  • Converts string s to integer.
  • Convert string s to integer using radix r.

Throws IllegalArgument when s cannot be converted.

Examples

rascal>import String;
ok
rascal>toInt("11");
int: 11
rascal>toInt("11", 8);
int: 9

Now try an erroneous argument:

rascal>toInt("abc");
|file:///Users/jurgenv/git/rascal/src/org/rascalmpl/library/String.rsc|(11107,480,<549,0>,<575,52>): IllegalArgument("abc","For input string: \"abc\"")
at *** somewhere ***(|file:///Users/jurgenv/git/rascal/src/org/rascalmpl/library/String.rsc|(11107,480,<549,0>,<575,52>))
at toInt(|prompt:///|(6,5,<1,6>,<1,11>))
ok

function toLowerCase

str toLowerCase(str s)

Synopsis

Convert the characters in a string value to lower case.

Description

Convert all characters in string s to lowercase. Also see to upper case.

Examples

rascal>import String;
ok
rascal>toLowerCase("AaBbCc123");
str: "aabbcc123"

function toReal

real toReal(str s)

Synopsis

Convert a string value to real.

Description

Converts string s to a real. Throws IllegalArgument when s cannot be converted.

Examples

rascal>import String;
ok
rascal>toReal("2.5e-3");
real: 0.0025
rascal>toReal("123");
real: 123.
rascal>toReal("abc");
|file:///Users/jurgenv/git/rascal/src/org/rascalmpl/library/String.rsc|(12024,338,<600,0>,<619,31>): IllegalArgument()
at *** somewhere ***(|file:///Users/jurgenv/git/rascal/src/org/rascalmpl/library/String.rsc|(12024,338,<600,0>,<619,31>))
at toReal(|prompt:///|(7,5,<1,7>,<1,12>))
ok

function toUpperCase

str toUpperCase(str s)

Synopsis

Convert the characters in a string value to upper case.

Description

Converts all characters in string s to upper case.

Also see to lower case.

Examples

rascal>import String;
ok
rascal>toUpperCase("AaBbCc123");
str: "AABBCC123"

function trim

str trim(str s)

Synopsis

Returns string with leading and trailing whitespace removed.

Examples

rascal>import String;
ok
rascal>trim(" jelly
>>>>>>>beans ");
str: "jelly\nbeans"

function squeeze

str squeeze(str src, str charSet)

Synopsis

Squeeze repeated occurrences of characters.

Description

Squeeze repeated occurrences in src of characters in charSet removed. See http://commons.apache.org/lang/api-2.6/index.html?org/apache/commons/lang/text/package-summary.html[Apache] for the allowed syntax in charSet.

Examples

rascal>import String;
ok
rascal>squeeze("hello", "el");
str: "helo"

function split

list[str] split(str sep, str src)

Synopsis

Split a string into a list of strings based on a literal separator.

function capitalize

str capitalize(str src)

function uncapitalize

str uncapitalize(str src)

function toBase64

str toBase64(str src)

function fromBase64

str fromBase64(str src)

function wrap

str wrap(str src, int wrapLength)

Synopsis

Word wrap a string to fit in a certain width.

Description

Inserts newlines in a string in order to fit the string in a certain width. It only breaks on spaces (' ').

function format

str format(str s, str dir, int n, str pad)

function rexpMatch

bool rexpMatch(str s, str re)

Synopsis

Determine if a string matches the given (Java-syntax) regular expression.

function toLocation

loc toLocation(str s)

Synopsis

Convert a string value to a (source code) location.

Description

  • Converts string s to a location.
  • If the scheme is not provided, it is assumed to be cwd.

Examples

rascal>import String;
ok
rascal>toLocation("http://grammarware.net");
loc: |http://grammarware.net|
rascal>toLocation("document.xml");
loc: |cwd:///document.xml|

function substitute

str substitute(str src, map[loc,str] s)

Synopsis

Substitute substrings in a string based on a substitution map from location to string.

Examples

rascal>import String;
ok
rascal>substitute("abc", (|stdin:///|(1,1): "d"))
str: "adc"