ballerina/lang.string

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

Joins zero or more strings together with a separator.

string:'join(" ", "Ballerina", "is", "a", "programming", "language") ⇒ Ballerina is a programming language
string[] array = ["John", "23", "USA", "Computer Science", "Swimmer"];
string:'join(",", ...array) ⇒ John,23,USA,Computer Science,Swimmer

function 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.

"Austria".codePointCompare("Australia") ⇒ 1

function concat(string... strs) returns string

Concatenates zero or more strings.

"http://worldtimeapi.org".concat("/api/timezone/", "Asia", "/", "Colombo") ⇒ http://worldtimeapi.org/api/timezone/Asia/Colombo
// Alternative approach to achieve the same.
string:concat("http://worldtimeapi.org", "/api/timezone/", "Asia", "/", "Colombo") ⇒ http://worldtimeapi.org/api/timezone/Asia/Colombo

function endsWith(string str, string substr) returns boolean

Tests whether a string ends with another string.

"Welcome to the Ballerina programming language".endsWith("language") ⇒ true

function 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.

"BALLERINA".equalsIgnoreCaseAscii("ballerina") ⇒ true

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

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

string:fromBytes([72, 101, 108, 108, 111, 32, 66, 97, 108, 108, 101, 114, 105, 110, 97, 33]) ⇒ Hello, World!
string:fromBytes([149, 169, 224]) ⇒ error

function 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.

string:fromCodePointInt(97) ⇒ a
string:fromCodePointInt(1114113) ⇒ error

function 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.

string:fromCodePointInts([66, 97, 108, 108, 101, 114, 105, 110, 97]) ⇒ Ballerina
string:fromCodePointInts([1114113, 1114114, 1114115]) ⇒ error

function getCodePoint(string str, int index) returns int

Returns the code point of a character in a string.

"Hello, World!".getCodePoint(3) ⇒ 108

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

Tests whether a string includes another string.

"Hello World, from Ballerina".includes("Bal") ⇒ true
"Hello World! from Ballerina".includes("Hello", 10) ⇒ false

function includesMatch(string str, RegExp re, int startIndex) returns boolean

Tests whether there is a match of a regular expression somewhere within a string. This is equivalent to regexp:find(re, str, startIndex) != ().

"This will match".includesMatch(re `Th.*ch`) ⇒ true
"Will this match".includesMatch(re `th.*ch`, 5) ⇒ true
"Not a match".includesMatch(re `Th.*ch`) ⇒ false
"Will this match".includesMatch(re `Th.*ch`, 5) ⇒ false

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

Finds the first occurrence of one string in another string.

"New Zealand".indexOf("land") ⇒ 7
"Ballerinalang is a unique programming language".indexOf("lang", 15) ⇒ 38

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

Returns an iterator over the string.

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

object {
  public isolated function next() returns record {|string:Char value;|}?;
} iterator = "Hello, World!".iterator();
iterator.next() ⇒ {"value":"H"}

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

Finds the last occurrence of one string in another string.

"Ballerinalang is a unique programming language".lastIndexOf("lang") ⇒ 38
// Search backwards for the last occurrence of a string from a specific index.
"Ballerinalang is a unique programming language".lastIndexOf("lang", 15) ⇒ 9

function length(string str) returns int

Returns the length of the string.

"Hello, World!".length() ⇒ 13;

function matches(string str, RegExp re) returns boolean

Tests whether there is a full match of a regular expression with a string. A match of a regular expression in a string is a full match if it starts at index 0 and ends at index n, where n is the length of the string. This is equivalent to regex:isFullMatch(re, str).

"This is a Match".matches(re `A|Th.*ch|^`) ⇒ true
"Not a Match".matches(re `A|Th.*ch|^`) ⇒ false

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

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.

"Ballerina for developers".padEnd(30) ⇒ Ballerina for developers
"Ballerina for developers".padEnd(30, "!") ⇒ Ballerina for developers!!!!!!

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

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.

"100Km".padStart(10) ⇒      100Km
"100Km".padStart(10, "0") ⇒ 00000100Km

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

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.

"-256".padZero(9) ⇒ -00000256
"-880".padZero(8, "#") ⇒ -####880

function startsWith(string str, string substr) returns boolean

Tests whether a string starts with another string.

"Welcome to the Ballerina programming language".startsWith("Welcome") ⇒ true

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

Returns a substring of a string.

"Hello, my name is John".substring(7) ⇒ my name is John
"Hello, my name is John Anderson".substring(18, 22) ⇒ John

function toBytes(string str) returns byte[]

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

"Hello, World!".toBytes() ⇒ [72,101,108,108,111,44,32,87,111,114,108,100,33]

function toCodePointInt(Char ch) returns int

Converts a single character string to a code point.

string:toCodePointInt("a") ⇒ 97

function toCodePointInts(string str) returns int[]

Converts a string to an array of code points.

"Hello, world 🌎".toCodePointInts() ⇒ [72,101,108,108,111,44,32,119,111,114,108,100,32,127758]

function toLowerAscii(string str) returns string

Converts occurrences of A-Z to a-z.

Other characters are left unchanged.

"HELLO, World!".toLowerAscii() ⇒ hello, world!

function toUpperAscii(string str) returns string

Converts occurrences of a-z to A-Z.

Other characters are left unchanged.

"hello, World!".toUpperAscii() ⇒ HELLO, WORLD!

function 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.

" Hello World   ".trim() + "!" ⇒ Hello World!