Language librarylang.string

functions

Functions

'join
I

Joins zero or more strings together with a separator.

codePointCompare
I

Lexicographically compares strings using their Unicode code points.

concat
I

Concatenates zero or more strings.

endsWith
I

Tests whether a string ends with another string.

equalsIgnoreCaseAscii
I

Tests whether two strings are the same, ignoring the case of ASCII characters.

fromBytes
I

Constructs a string from its UTF-8 representation in bytes.

fromCodePointInt
I

Constructs a single character string from a code point.

fromCodePointInts
I

Constructs a string from an array of code points.

getCodePoint
I

Returns the code point of a character in a string.

includes
I

Tests whether a string includes another string.

indexOf
I

Finds the first occurrence of one string in another string.

iterator
I

Returns an iterator over the string.

lastIndexOf
I

Finds the last occurrence of one string in another string.

length
I

Returns the length of the string.

padEnd
I

Adds padding to the end of a string.

padStart
I

Adds padding to the start of a string.

padZero
I

Pads a string with zeros.

startsWith
I

Tests whether a string starts with another string.

substring
I

Returns a substring of a string.

toBytes
I

Represents a string as an array of bytes using UTF-8.

toCodePointInt
I

Converts a single character string to a code point.

toCodePointInts
I

Converts a string to an array of code points.

toLowerAscii
I

Converts occurrences of A-Z to a-z.

toUpperAscii
I

Converts occurrences of a-z to A-Z.

trim
I

Removes ASCII white space characters from the start and end of a string.

'join 

function 'join(string separator, string... strs) returns string
Isolated Function

Joins zero or more strings together with a separator.

Parameters

  • separator string

    • separator string

  • strs string...

    • strings to be joined

Return Type

(string)

a string consisting of all of parameter strs concatenated in order with parameter separator in between them

codePointCompare 

function codePointCompare(string str1, string str2) returns int
Isolated Function

Lexicographically compares strings using their Unicode code points.

This orders strings in a consistent and well-defined way, but the ordering will often not be consistent with cultural expectations for sorted order.

Parameters

  • str1 string

    • the first string to be compared

  • str2 string

    • the second string to be compared

Return Type

(int)

an int that is less than, equal to or greater than zero, according as parameter str1 is less than, equal to or greater than parameter str2

concat 

function concat(string... strs) returns string
Isolated Function

Concatenates zero or more strings.

Parameters

  • strs string...

    • strings to be concatenated

Return Type

(string)

concatenation of all of the parameter strs; empty string if parameter strs is empty

endsWith 

function endsWith(string str, string substr) returns boolean
Isolated Function

Tests whether a string ends with another string.

Parameters

  • str string

    • the string to be tested

  • substr string

    • the ending string

Return Type

(boolean)

true if parameter str ends with parameter substr; false otherwise

equalsIgnoreCaseAscii 

function equalsIgnoreCaseAscii(string str1, string str2) returns boolean
Isolated Function

Tests whether two strings are the same, ignoring the case of ASCII characters.

A character in the range a-z is treated the same as the corresponding character in the range A-Z.

Parameters

  • str1 string

    • the first string to be compared

  • str2 string

    • the second string to be compared

Return Type

(boolean)

true if parameter str1 is the same as parameter str2, treating upper-case and lower-case ASCII letters as the same; false, otherwise

fromBytes 

function fromBytes(byte[ ] bytes) returns string | error
Isolated Function

Constructs a string from its UTF-8 representation in bytes.

Parameters

  • bytes byte[ ]

    • UTF-8 byte array

Return Type

(string | error)

parameter bytes converted to string or error

fromCodePointInt 

function fromCodePointInt(int codePoint) returns Char | error
Isolated Function

Constructs a single character string from a code point.

An int is a valid code point if it is in the range 0 to 0x10FFFF inclusive, but not in the range 0xD800 or 0xDFFF inclusive.

Parameters

  • codePoint int

    • an int specifying a code point

Return Type

(Char | error)

a single character string whose code point is parameter codePoint; or an error if parameter codePoint is not a valid code point

fromCodePointInts 

function fromCodePointInts(int[ ] codePoints) returns string | error
Isolated Function

Constructs a string from an array of code points.

An int is a valid code point if it is in the range 0 to 0x10FFFF inclusive, but not in the range 0xD800 or 0xDFFF inclusive.

Parameters

  • codePoints int[ ]

    • an array of ints, each specifying a code point

Return Type

(string | error)

a string with a character for each code point in parameter codePoints; or an error if any member of parameter codePoints is not a valid code point

getCodePoint 

function getCodePoint(string str, int index) returns int
Isolated Function

Returns the code point of a character in a string.

Parameters

  • index int

    • an index in parameter str

Return Type

(int)

the Unicode code point of the character at parameter index in parameter str

includes 

function includes(string str, string substr, int startIndex) returns boolean
Isolated Function

Tests whether a string includes another string.

Parameters

  • str string

    • the string in which to search

  • substr string

    • the string to search for

  • startIndex int (default 0)

    • index to start searching from

Return Type

(boolean)

true if there is an occurrence of parameter substr in parameter str at an index >= parameter startIndex, or false otherwise

indexOf 

function indexOf(string str, string substr, int startIndex) returns int?
Isolated Function

Finds the first occurrence of one string in another string.

Parameters

  • str string

    • the string in which to search

  • substr string

    • the string to search for

  • startIndex int (default 0)

    • index to start searching from

Return Type

(int?)

index of the first occurrence of parameter substr in parameter str that is >= parameter startIndex, or () if there is no such occurrence

iterator 

function iterator(string str) returns object {
    public isolated function next() returns record {| Char value; |}?;
}
Isolated Function

Returns an iterator over the string.

The iterator will yield the substrings of length 1 in order.

Parameters

  • str string

    • the string to be iterated over

Return Type

(object { public isolated function next() returns record {| Char value; |}?; })

a new iterator object

lastIndexOf 

function lastIndexOf(string str, string substr, int startIndex) returns int?
Isolated Function

Finds the last occurrence of one string in another string.

Parameters

  • str string

    • the string in which to search

  • substr string

    • the string to search for

  • startIndex int (default str.length() - substr.length())

    • index to start searching backwards from

Return Type

(int?)

index of the last occurrence of parameter substr in parameter str that is <= parameter startIndex, or () if there is no such occurrence

length 

function length(string str) returns int
Isolated Function

Returns the length of the string.

Parameters

Return Type

(int)

the number of characters (code points) in parameter str

padEnd 

function padEnd(string str, int len, Char padChar) returns string
Isolated Function

Adds padding to the end of a string. Adds sufficient padChar characters to the end of str to make its length be len. If the length of str is >= len, returns str.

Parameters

  • len int

    • the length of the string to be returned

  • padChar Char (default " ")

    • the character to use for padding str; defaults to a space character

Return Type

(string)

str padded with padChar

padStart 

function padStart(string str, int len, Char padChar) returns string
Isolated Function

Adds padding to the start of a string. Adds sufficient padChar characters at the start of str to make its length be len. If the length of str is >= len, returns str.

Parameters

  • len int

    • the length of the string to be returned

  • padChar Char (default " ")

    • the character to use for padding str; defaults to a space character

Return Type

(string)

str padded with padChar

padZero 

function padZero(string str, int len, Char zeroChar) returns string
Isolated Function

Pads a string with zeros. The zeros are added at the start of the string, after a + or - sign if there is one. Sufficient zero characters are added to str to make its length be len. If the length of str is >= len, returns str.

Parameters

  • len int

    • the length of the string to be returned

  • zeroChar Char (default "0")

    • the character to use for the zero; defaults to ASCII zero 0

Return Type

(string)

str padded with zeros

startsWith 

function startsWith(string str, string substr) returns boolean
Isolated Function

Tests whether a string starts with another string.

Parameters

  • str string

    • the string to be tested

  • substr string

    • the starting string

Return Type

(boolean)

true if parameter str starts with parameter substr; false otherwise

substring 

function substring(string str, int startIndex, int endIndex) returns string
Isolated Function

Returns a substring of a string.

Parameters

  • startIndex int

    • the starting index, inclusive

  • endIndex int (default str.length())

    • the ending index, exclusive

Return Type

(string)

substring consisting of characters with index >= startIndex and < endIndex

toBytes 

function toBytes(string str) returns byte[ ]
Isolated Function

Represents a string as an array of bytes using UTF-8.

Parameters

Return Type

(byte[ ])

UTF-8 byte array

toCodePointInt 

function toCodePointInt(Char ch) returns int
Isolated Function

Converts a single character string to a code point.

Parameters

  • ch Char

    • a single character string

Return Type

(int)

the code point of parameter ch

toCodePointInts 

function toCodePointInts(string str) returns int[ ]
Isolated Function

Converts a string to an array of code points.

Parameters

Return Type

(int[ ])

an array with a code point for each character of parameter str

toLowerAscii 

function toLowerAscii(string str) returns string
Isolated Function

Converts occurrences of A-Z to a-z.

Other characters are left unchanged.

Parameters

  • str string

    • the string to be converted

Return Type

(string)

parameter str with any occurrences of A-Z converted to a-z

toUpperAscii 

function toUpperAscii(string str) returns string
Isolated Function

Converts occurrences of a-z to A-Z.

Other characters are left unchanged.

Parameters

  • str string

    • the string to be converted

Return Type

(string)

parameter str with any occurrences of a-z converted to A-Z

trim 

function trim(string str) returns string
Isolated Function

Removes ASCII white space characters from the start and end of a string.

The ASCII white space characters are 0x9...0xD, 0x20.

Parameters

Return Type

(string)

parameter str with leading or trailing ASCII white space characters removed