9.5.12 Strings

String manipulation and query functions.

concat( s1, s2 )

Concatenates two strings. In most cases the same effect can be achieved by writing s1+s2, but blank values can sometimes appear as the string "null" if you do it like that.

• s1 (String): first string
• s2 (String): second string
• return value (String): s1 followed by s2

concat( s1, s2, s3 )

Concatenates three strings. In most cases the same effect can be achieved by writing s1+s2+s3, but blank values can sometimes appear as the string "null" if you do it like that.

• s1 (String): first string
• s2 (String): second string
• s3 (String): third string
• return value (String): s1 followed by s2 followed by s3

concat( s1, s2, s3, s4 )

Concatenates four strings. In most cases the same effect can be achieved by writing s1+s2+s3+s4, but blank values can sometimes appear as the string "null" if you do it like that.

• s1 (String): first string
• s2 (String): second string
• s3 (String): third string
• s4 (String): fourth string
• return value (String): s1 followed by s2 followed by s3 followed by s4

equals( s1, s2 )

Determines whether two strings are equal. Note you should use this function instead of s1==s2, which can (for technical reasons) return false even if the strings are the same.

• s1 (String): first string
• s2 (String): second string
• return value (boolean): true if s1 and s2 are both blank, or have the same content

equalsIgnoreCase( s1, s2 )

Determines whether two strings are equal apart from possible upper/lower case distinctions.

• s1 (String): first string
• s2 (String): second string
• return value (boolean): true if s1 and s2 are both blank, or have the same content apart from case folding

startsWith( whole, start )

Determines whether a string starts with a certain substring.

• whole (String): the string to test
• start (String): the sequence that may appear at the start of whole
• return value (boolean): true if the first few characters of whole are the same as start

endsWith( whole, end )

Determines whether a string ends with a certain substring.

• whole (String): the string to test
• end (String): the sequence that may appear at the end of whole
• return value (boolean): true if the last few characters of whole are the same as end

contains( whole, sub )

Determines whether a string contains a given substring.

• whole (String): the string to test
• sub (String): the sequence that may appear within whole
• return value (boolean): true if the sequence sub appears within whole

length( str )

Returns the length of a string in characters.

• str (String): string
• return value (integer): number of characters in str

split( words )

Splits a string into an array of space-separated words. One or more spaces separates each word from the next. Leading and trailing spaces are ignored.

The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with [0] representing the first object

• words (String): string with embedded spaces delimiting the words
• return value (array of String): array of the separate words; you can extract the individual words from the result using square bracket indexing

split( words, regex )

Splits a string into an array of words separated by a given regular expression.

The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with [0] representing the first object

• words (String): string with multiple parts
• regex (String): regular expression delimiting the different words in the words parameter
• return value (array of String): array of the separate words; you can extract the individual words from the result using square bracket indexing

matches( str, regex )

Tests whether a string matches a given regular expression.

• str (String): string to test
• regex (String): regular expression string
• return value (boolean): true if regex matches str anywhere

matchGroup( str, regex )

Returns the first grouped expression matched in a string defined by a regular expression. A grouped expression is one enclosed in parentheses.

• str (String): string to match against
• regex (String): regular expression containing a grouped section
• return value (String): contents of the matched group (or null, if regex didn't match str)

replaceFirst( str, regex, replacement )

Replaces the first occurrence of a regular expression in a string with a different substring value.

• str (String): string to manipulate
• regex (String): regular expression to match in str
• replacement (String): replacement string
• return value (String): same as str, but with the first match (if any) of regex replaced by replacement

replaceAll( str, regex, replacement )

Replaces all occurrences of a regular expression in a string with a different substring value.

• str (String): string to manipulate
• regex (String): regular expression to match in str
• replacement (String): replacement string
• return value (String): same as str, but with all matches of regex replaced by replacement

substring( str, startIndex )

Returns the last part of a given string. The substring begins with the character at the specified index and extends to the end of this string.

• str (String): the input string
• startIndex (integer): the beginning index, inclusive
• return value (String): last part of str, omitting the first startIndex characters

substring( str, startIndex, endIndex )

Returns a substring of a given string. The substring begins with the character at startIndex and continues to the character at index endIndex-1 Thus the length of the substring is endIndex-startIndex.

• str (String): the input string
• startIndex (integer): the beginning index, inclusive
• endIndex (integer): the end index, inclusive
• return value (String): substring of str

toUpperCase( str )

Returns an uppercased version of a string.

• str (String): input string
• return value (String): uppercased version of str

toLowerCase( str )

Returns an uppercased version of a string.

• str (String): input string
• return value (String): uppercased version of str

trim( str )

Trims whitespace from both ends of a string.

• str (String): input string
• return value (String): str with any spaces trimmed from start and finish

padWithZeros( value, ndigit )

Takes an integer argument and returns a string representing the same numeric value but padded with leading zeros to a specified length.

• value (long integer): numeric value to pad
• ndigit (integer): the number of digits in the resulting string
• return value (String): a string evaluating to the same as value with at least ndigit characters