lang.string
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
strs
concatenated in order with parameterseparator
in 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
str1
is 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 parameterstrs
is 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
str
ends 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
str1
is 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
index
in 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 -
true
if there is an occurrence of parametersubstr
in parameterstr
at an index >= parameterstartIndex
, orfalse
otherwise
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
re
somewhere 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
substr
in parameterstr
that 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
substr
in parameterstr
that 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
re
withstr
, 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 -
str
padded 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 -
str
padded 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 -
str
padded 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
str
starts 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 >=
startIndex
and <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
str
with 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
str
with 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
str
with leading or trailing ASCII white space characters removed
Simple name reference types
lang.string: RegExp
RegExp
Refers to the RegExp
type defined by lang.regexp module.