Module lang.string
ballerina/lang.string Ballerina library
Module overview
The lang.string module corresponds to the string basic type.
Functions
'join
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
Return Type
- string - a string consisting of all of parameter
strsconcatenated in order with parameterseparatorin between them
codePointCompare
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
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
str1is less than, equal to or greater than parameterstr2
concat
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
Parameters
- strs string... - strings to be concatenated
Return Type
- string - concatenation of all of the parameter
strs; empty string if parameterstrsis empty
endsWith
Tests whether a string ends with another string.
"Welcome to the Ballerina programming language".endsWith("language") ⇒ true
Return Type
- boolean - true if parameter
strends with parametersubstr; false otherwise
equalsIgnoreCaseAscii
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
Parameters
- str1 string - the first string to be compared
- str2 string - the second string to be compared
Return Type
- boolean - true if parameter
str1is the same as parameterstr2, treating upper-case and lower-case ASCII letters as the same; false, otherwise
fromBytes
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
Parameters
- bytes byte[] - UTF-8 byte array
fromCodePointInt
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
Parameters
- codePoint int - an int specifying a code point
fromCodePointInts
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
Parameters
- codePoints int[] - an array of ints, each specifying a code point
getCodePoint
Returns the code point of a character in a string.
"Hello, World!".getCodePoint(3) ⇒ 108
Return Type
- int - the Unicode code point of the character at parameter
indexin parameterstr
includes
Tests whether a string includes another string.
"Hello World, from Ballerina".includes("Bal") ⇒ true "Hello World! from Ballerina".includes("Hello", 10) ⇒ false
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 -
trueif there is an occurrence of parametersubstrin parameterstrat an index >= parameterstartIndex, orfalseotherwise
includesMatch
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
Parameters
- str string - the string to be matched
- re RegExp - the regular expression
- startIndex int (default 0) -
Return Type
- boolean - true if the is a match of
resomewhere withinstr, otherwise false
indexOf
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
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
substrin parameterstrthat is >= parameterstartIndex, or()if there is no such occurrence
iterator
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"}
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
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
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
substrin parameterstrthat is <= parameterstartIndex, or()if there is no such occurrence
length
Returns the length of the string.
"Hello, World!".length() ⇒ 13;
Parameters
- str string - the string
Return Type
- int - the number of characters (code points) in parameter
str
matches
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
Return Type
- boolean - true if there is full match of
rewithstr, and false otherwise
padEnd
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!!!!!!
Parameters
- str string - the string to pad
- 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 -
strpadded withpadChar
padStart
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
Parameters
- str string - the string to pad
- 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 -
strpadded withpadChar
padZero
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
Parameters
- str string - the string to pad
- 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 -
strpadded with zeros
startsWith
Tests whether a string starts with another string.
"Welcome to the Ballerina programming language".startsWith("Welcome") ⇒ true
Return Type
- boolean - true if parameter
strstarts with parametersubstr; false otherwise
substring
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
Parameters
- str string - source string.
- startIndex int - the starting index, inclusive
- endIndex int (default str.length()) - the ending index, exclusive
Return Type
- string - substring consisting of characters with index >=
startIndexand <endIndex
toBytes
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]
Parameters
- str string - the string
Return Type
- byte[] - UTF-8 byte array
toCodePointInt
Converts a single character string to a code point.
string:toCodePointInt("a") ⇒ 97
Parameters
- ch Char - a single character string
Return Type
- int - the code point of parameter
ch
toCodePointInts
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]
Parameters
- str string - the string
Return Type
- int[] - an array with a code point for each character of parameter
str
toLowerAscii
Converts occurrences of A-Z to a-z.
Other characters are left unchanged.
"HELLO, World!".toLowerAscii() ⇒ hello, world!
Parameters
- str string - the string to be converted
Return Type
- string - parameter
strwith any occurrences of A-Z converted to a-z
toUpperAscii
Converts occurrences of a-z to A-Z.
Other characters are left unchanged.
"hello, World!".toUpperAscii() ⇒ HELLO, WORLD!
Parameters
- str string - the string to be converted
Return Type
- string - parameter
strwith any occurrences of a-z converted to A-Z
trim
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!
Parameters
- str string - the string
Return Type
- string - parameter
strwith leading or trailing ASCII white space characters removed
String types
lang.string: Char
Char
Built-in subtype of string containing strings of length 1.
Simple name reference types
lang.string: RegExp
RegExp
Refers to the RegExp type defined by lang.regexp module.