This API documentation is for Ballerina 1.2.0. View API documentation for the latest release.

Functions - lang.string

codePointCompare

Lexicographically compares strings using their Unicode code points.

concat

Concatenates zero or more strings.

endsWith

Tests whether a string ends with another string.

equalsIgnoreCaseAscii

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

fromBytes

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

fromCodePointInt

Constructs a single character string from a code point.

fromCodePointInts

Constructs a string from an array of code points.

getCodePoint

Returns the code point of a character in a string.

indexOf

Finds the first occurrence of one string in another string.

iterator

Returns an iterator over the string.

join

Joins zero or more strings together with a separator.

lastIndexOf

Finds the last occurrence of one string in another string.

length

Returns the length of the string.

startsWith

Tests whether a string starts with another string.

substring

Returns a substring of a string.

toBytes

Represents str as an array of bytes using UTF-8.

toCodePointInt

Converts a single character string to a code point.

toCodePointInts

Converts a string to an array of code points.

toLowerAscii

Converts occurrences of A-Z to a-z.

toUpperAscii

Converts occurrences of a-z to A-Z.

trim

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

codePointCompare

(string str1, string str2)

returns int

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 str1 is less than, equal to or greater than str2

concat

(string... strs)

returns string

Concatenates zero or more strings.

Parameters

  • strs string...
  • strings to be concatenated

  • Return Type

    (string)
  • concatenation of all of the strs; empty string if strs is empty

endsWith

(string str, string substr)

returns boolean

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 str ends with substr; false otherwise

equalsIgnoreCaseAscii

(string str1, string str2)

returns boolean

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 str1 is the same as str2, treating upper-case and lower-case ASCII letters as the same; false, otherwise

fromBytes

(byte[] bytes)

returns string | error

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

Parameters

  • bytes byte[]
  • UTF-8 byte array

  • Return Type

    (string | error)
  • bytes converted to string or error

fromCodePointInt

(int codePoint)

returns Char | error

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 codePoint; or an error if codePoint is not a valid code point

fromCodePointInts

(int[] codePoints)

returns string | error

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 codePoints; or an error if any member of codePoints is not a valid code point

getCodePoint

(string str, int index)

returns int

Returns the code point of a character in a string.

Parameters

  • str string
  • the string

  • index int
  • an index in str

  • Return Type

    (int)
  • the Unicode code point of the character at index in str

indexOf

(string str, string substr, int startIndex)

returns int?

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 substr in str that is >= startIndex, or () if there is no such occurrence

iterator

(string str)

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

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 function next () returns (record {| string value; |}?); })
  • a new iterator object

join

(string separator, string... strs)

returns string

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 strs concatenated in order with separator in between them

lastIndexOf

(string str, string substr, int startIndex)

returns int?

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(str) - substr.length(substr))
  • index to start searching backwards from

  • Return Type

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

length

(string str)

returns int

Returns the length of the string.

Parameters

  • str string
  • the string

  • Return Type

    (int)
  • the number of characters (code points) in str

startsWith

(string str, string substr)

returns boolean

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 str starts with substr; false otherwise

substring

(string str, int startIndex, int endIndex)

returns string

Returns a substring of a string.

Parameters

  • str string
  • source string.

  • startIndex int
  • the starting index, inclusive

  • endIndex int (default str.length(str))
  • the ending index, exclusive

  • Return Type

    (string)
  • substring consisting of characters with index >= startIndex and < endIndex

toBytes

(string str)

returns byte[]

Represents str as an array of bytes using UTF-8.

Parameters

  • str string
  • the string

  • Return Type

    (byte[])
  • UTF-8 byte array

toCodePointInt

(Char ch)

returns int

Converts a single character string to a code point.

Parameters

  • ch Char
  • a single character string

  • Return Type

    (int)
  • the code point of ch

toCodePointInts

(string str)

returns int[]

Converts a string to an array of code points.

Parameters

  • str string
  • the string

  • Return Type

    (int[])
  • an array with a code point for each character of str

toLowerAscii

(string str)

returns string

Converts occurrences of A-Z to a-z. Other characters are left unchanged.

Parameters

  • str string
  • the string to be converted

  • Return Type

    (string)
  • str with any occurrences of A-Z converted to a-z

toUpperAscii

(string str)

returns string

Converts occurrences of a-z to A-Z. Other characters are left unchanged.

Parameters

  • str string
  • the string to be converted

  • Return Type

    (string)
  • str with any occurrences of a-z converted to A-Z

trim

(string str)

returns string

Removes ASCII white space characters from the start and end of a string. The ASCII white space characters are 0x9...0xD, 0x20.

Parameters

  • str string
  • the string

  • Return Type

    (string)
  • str with leading or trailing ASCII white space characters removed