A string of characters. Each character in the string is a 32-bit Unicode character. The UTF-16 encoding of the underlying native string is hidden from clients.
Literal strings may be written between double quotes:
"hello world" "\r\n" "\{#03C0} \{#2248} 3.14159" "\{GREEK SMALL LETTER PI} \{ALMOST EQUAL TO} 3.14159"
Alternatively, a verbatim string may be written between tripled double quotes.
The empty string, ""
, is a string with no
characters.
A string is a Category
of its characters
, and
of its substrings:
'w' in greeting "hello" in greeting
Strings are summable:
String greeting = "hello" + " " + "world";
They are efficiently iterable:
for (char in "hello world") { ... }
They are lists of characters:
value char = "hello world"[5];
They are ranged:
String who = "hello world"[6...];
Note that since string[index]
evaluates to the
optional type Character?
, it is often more
convenient to write string[index..index]
, which
evaluates to a String
containing a single character,
or to the empty string ""
if index
refers to a
position outside the string.
It is easy to use comprehensions to transform strings:
String { for (s in "hello world") if (s.letter) s.uppercased }
Since a String
has an underlying UTF-16-encoded
native string, certain operations are expensive,
requiring iteration of the characters of the string.
In particular, size
requires iteration of the
whole string, and get()
, span()
, and measure()
require iteration from the beginning of the string to
the given index.
no subtypes hierarchy
Constructors | |
String | Source Codeshared String({Character*} characters) A new string with the given |
Attributes | |
coalesced | Source Codeshared actual String coalesced This string. Refines Iterable.coalesced |
empty | Source Codeshared actual Boolean empty |
first | Source Codeshared actual Character? first The first character in the string. |
hash | Source Codeshared actual Integer hash A hash code for this |
keys | Source Codeshared actual Integer[] keys A sequence containing all indexes of this string. |
last | Source Codeshared actual Character? last The last character in the string. |
lastIndex | Source Codeshared actual Integer? lastIndex The index of the last character in the string, or
string.lastIndex == string.size-1 Refines List.lastIndex |
length | See size |
lines | Source Codeshared {String+} lines Split the string into lines of text, discarding
line breaks. Recognized line break sequences are
See also linesWithBreaks |
linesWithBreaks | Source Codeshared {String+} linesWithBreaks Split the string into lines of text with line
breaks. Each line will be terminated by a line
break sequence, See also lines Since 1.1.0 |
lowercased | Source Codeshared String lowercased This string, with all characters in lowercase. Conversion of uppercase characters to lowercase is
performed according to a locale-independent mapping
that produces incorrect results in certain locales
(e.g. The resulting string may not have the same number of characters as this string, since the uppercase representation of certain characters comprises multiple characters, for example the lowercase representation of İ is two characters wide. See also uppercased |
normalized | Source Codeshared String normalized A string containing the characters of this string after collapsing strings of adjacent whitespace characters into single space characters and discarding whitespace from the beginning and end of the string. |
rest | Source Codeshared actual String rest The rest of the string, without its first character. |
reversed | Source Codeshared actual String reversed A string containing the characters of this string, with the characters in reverse order. Refines List.reversed |
size | Source Codeshared actual Integer size The length of the string (the number of characters
it contains). In the case of the empty string, the
string has length zero. Note that this operation is
potentially costly for long strings, since the
underlying representation of the characters uses a
UTF-16 encoding. Use of See also longerThan() , shorterThan() Aliases: length |
string | Source Codeshared actual String string This string. |
trimmed | Source Codeshared String trimmed A string containing the characters of this string, after discarding whitespace from the beginning and end of the string. |
uppercased | Source Codeshared String uppercased This string, with all characters in uppercase. Conversion of lowercase characters to uppercase is
performed according to a locale-independent mapping
that produces incorrect results in certain locales
(e.g. The resulting string may not have the same number of characters as this string, since the uppercase representation of certain characters comprises multiple characters, for example the uppercase representation of ß is SS. See also lowercased |
whitespace | Source Codeshared Boolean whitespace Determine if this string contains only
whitespace characters.
Returns |
Inherited Attributes |
Attributes inherited from: Object |
Attributes inherited from: Collection<Element> |
Attributes inherited from: Correspondence<Key,Item> |
Attributes inherited from: Iterable<Element,Absent> |
Attributes inherited from: List<Element> |
Methods | |
any | Source Codeshared actual Boolean any(Boolean selecting(Character element)) Determines if there is at least one element of this
stream that satisfies the given predicate
function. If the stream is empty, returns
Refines Iterable.any |
clone | Source Codeshared actual String clone() This string. |
compare | Source Codeshared actual Comparison compare(String other) Compare this string with the given string lexicographically, according to the Unicode code points of the characters. This defines a locale-independent collation that is incorrect in some locales. For more specialized lexicographic comparisons
between strings, use See also compareIgnoringCase() , compareCorresponding() Refines Comparable.compare |
compareIgnoringCase | Source Codeshared Comparison compareIgnoringCase(String other) Compare this string with the given string
lexicographically, ignoring the case of the
characters. That is, by considering two characters
This defines a locale-independent collation that is incorrect in some locales. For more specialized lexicographic comparisons
between strings, use Since 1.2.0 |
contains | Source Codeshared actual Boolean contains(Object element) Determines if the given object is a Using the |
copyTo | Source Codeshared void copyTo(Array<in Character> destination, Integer sourcePosition = 0, Integer destinationPosition = 0, Integer length = ...) Efficiently copy the characters in the segment
The given
If the given Parameters:
Throws
Since 1.2.0 |
count | Source Codeshared actual Integer count(Boolean selecting(Character element)) Produces the number of elements in this stream that satisfy the given predicate function. For an infinite stream, this method never terminates. Refines Iterable.count |
defines | Source Codeshared actual Boolean defines(Integer index) Determines if this string contains a character at
the given |
each | Source Codeshared actual void each(void step(Character element)) Call the given function for each element of this stream, passing the elements in the order they occur in this stream. For example: words.each((word) { print(word.lowercased); print(word.uppercased); }); Has the same effect as the following for (word in words) { print(word.lowercased); print(word.uppercased); } For certain streams this method is highly efficient,
surpassing the performance of Refines Iterable.each |
endsWith | Source Codeshared actual Boolean endsWith(List<Anything> substring) Determines if this string ends with the characters
of the given string or list. Returns Parameters:
Refines List.endsWith |
equals | Source Codeshared actual Boolean equals(Object that) Determines if the given object is a For more specialized character-wise comparisons
between strings, use See also equalsIgnoringCase() , corresponding() |
equalsIgnoringCase | Source Codeshared Boolean equalsIgnoringCase(String that) Compare this string with the given string, ignoring
the case of the characters. That is, by considering
two characters
For more specialized character-wise comparisons
between strings, use Since 1.2.0 |
every | Source Codeshared actual Boolean every(Boolean selecting(Character element)) Determines if all elements of this stream satisfy the
given predicate function. If the stream
is empty, return Refines Iterable.every |
find | Source Codeshared actual Character? find(Boolean selecting(Character element)) The first element of this stream which is not null and
satisfies the given predicate function,
if any, or For example, the expression (-10..10).find(Integer.positive) evaluates to |
findLast | Source Codeshared actual Character? findLast(Boolean selecting(Character element)) The last element of this stream which is not null and
satisfies the given predicate function,
if any, or For example, the expression (-10..10).findLast(3.divides) evaluates to |
firstInclusion | Source Codeshared actual Integer? firstInclusion(List<Character> sublist, Integer from) The first index in this list at which the given list occurs as a sublist, that is greater than or equal to the optional starting index. Refines SearchableList.firstInclusion |
firstIndexWhere | Source Codeshared actual Integer? firstIndexWhere(Boolean selecting(Character element)) The first index in this list for which the element is not null and satisfies the given predicate function. Refines List.firstIndexWhere |
firstOccurrence | Source Codeshared actual Integer? firstOccurrence(Character element, Integer from, Integer length) The first index in this list at which the given
value occurs, that falls within the segment
Refines SearchableList.firstOccurrence |
getFromFirst | Source Codeshared actual Character? getFromFirst(Integer index) Returns the character at the given Using the item operator,
Parameters:
See also getFromLast() |
getFromLast | Source Codeshared actual Character? getFromLast(Integer index) Get the character at the specified index, where the
string is indexed from the end of the string, or
Parameters:
See also getFromFirst() Refines List.getFromLast |
includes | Source Codeshared actual Boolean includes(List<Character> sublist, Integer from) Determine if the given list occurs as a sublist at some index in this list, at any index that is greater than or equal to the optional starting index. Refines SearchableList.includes |
includesAt | Source Codeshared actual Boolean includesAt(Integer index, List<Character> sublist) Determine if the given list occurs as a sublist at the given index of this list. Refines SearchableList.includesAt |
inclusions | Source Codeshared actual {Integer*} inclusions(List<Character> sublist, Integer from) The indexes in this list at which the given list occurs as a sublist, that are greater than or equal to the optional starting index. Refines SearchableList.inclusions |
indexOf | Source Codeshared Integer indexOf(String string, Integer from = 0) The first index greater than or equal to the given
start index at which the given substring
occurs in this string, if any, or For any string.indexOf(substring, from) == string.firstInclusion(substring, from) else -1 Note: this operation is provided to ease migration
of code written in other languages. It is more
idiomatic to use Parameters:
See also firstInclusion() Since 1.3.0 |
indexesWhere | Source Codeshared actual {Integer*} indexesWhere(Boolean selecting(Character element)) The indexes in this list for which the element is not null and satisfies the given predicate function. Refines List.indexesWhere |
initial | Source Codeshared actual String initial(Integer length) Select the first characters of this string,
returning a string no longer than the given
Refines List.initial |
iterator | Source Codeshared actual Iterator<Character> iterator() An iterator for the characters of the string. |
join | Source Codeshared String join({Object*} objects) Join the string representations
of the given |
largerThan | Source Codeshared actual Boolean largerThan(String other) Determines if this string occurs after the given
string in lexicographic order, returning Refines Comparable.largerThan |
lastInclusion | Source Codeshared actual Integer? lastInclusion(List<Character> sublist, Integer from) The last index in this list at which the given
list occurs as a sublist, that falls within
the range Refines SearchableList.lastInclusion |
lastIndexOf | Source Codeshared Integer lastIndexOf(String string, Integer to = ...) The last index smaller than or equal to the given
end index at which the given substring
occurs in this string, if any, or For any string.lastIndexOf(substring, from) == string.lastInclusion(substring, string.size-from) else -1 Note: this operation is provided to ease migration
of code written in other languages. It is more
idiomatic to use Parameters:
See also lastInclusion() Since 1.3.0 |
lastIndexWhere | Source Codeshared actual Integer? lastIndexWhere(Boolean selecting(Character element)) The last index in this list for which the element is not null and satisfies the given predicate function. Refines List.lastIndexWhere |
lastOccurrence | Source Codeshared actual Integer? lastOccurrence(Character element, Integer from, Integer length) The last index in this list at which the given
value occurs, that falls within the range
Refines SearchableList.lastOccurrence |
locate | Source Codeshared actual <Integer->Character>? locate(Boolean selecting(Character element)) The first element of this stream which is not null and
satisfies the given predicate function,
if any, together with its position in the stream, or
For example, the expression (-10..10).locate(Integer.positive) evaluates to Refines Iterable.locate |
locateLast | Source Codeshared actual <Integer->Character>? locateLast(Boolean selecting(Character element)) The last element of this stream which is not null and
satisfies the given predicate function,
if any, together with its position in the stream, or
For example, the expression (-10..10).locateLast(3.divides) evaluates to Refines Iterable.locateLast |
locations | Source Codeshared actual {<Integer->Character>*} locations(Boolean selecting(Character element)) A stream producing all elements of this stream which are not null and which satisfy the given predicate function, together with their positions in the stream. For example, the expression (-5..5).locations(3.divides) evaluates to the stream Note that this method is more efficient than the
alternative of applying Refines Iterable.locations |
longerThan | Source Codeshared actual Boolean longerThan(Integer length) |
measure | Source Codeshared actual String measure(Integer from, Integer length) A string containing the characters of this string
beginning at the given start index,
returning a string no longer than the given
Using the measure operator,
|
notLargerThan | Source Codeshared actual Boolean notLargerThan(String other) Determines if this string occurs before the given
string in lexicographic order, returning Refines Comparable.notLargerThan |
notSmallerThan | Source Codeshared actual Boolean notSmallerThan(String other) Determines if this string occurs after the given
string in lexicographic order, returning Refines Comparable.notSmallerThan |
occurrences | Source Codeshared actual {Integer*} occurrences(Character element, Integer from, Integer length) The indexes in this list at which the given value occurs. Refines SearchableList.occurrences |
occurs | Source Codeshared actual Boolean occurs(Character element, Integer from, Integer length) Determines if the given value occurs as an
element of this list, at any index that falls within
the segment Refines SearchableList.occurs |
occursAt | Source Codeshared actual Boolean occursAt(Integer index, Character element) Determines if the given value occurs at the given index in this list. Refines SearchableList.occursAt |
pad | Source Codeshared String pad(Integer size, Character character = ...) |
padLeading | Source Codeshared String padLeading(Integer size, Character character = ...) |
padTrailing | Source Codeshared String padTrailing(Integer size, Character character = ...) |
plus | Source Codeshared actual String plus(String other) Returns the concatenation of this string with the given string. The resulting string contains the characters of this string followed by the characters of the given string. Using the addition operator,
Refines Summable.plus |
reduce | Source Codeshared actual Result|Character|Null reduce<Result>(Result accumulating(Result|Character partial, Character element)) Beginning with the For an empty stream, For a stream with one element, { first }.reduce(f) == first For a given stream it.reduce(f) == f(it.exceptLast.reduce(f), it.last) For example, the expression (1..100).reduce(plus) results in the integer Refines Iterable.reduce |
removeInitial | Source Codeshared String removeInitial(String prefix) Returns a string formed by removing the given
Since 1.3.0 |
removeTerminal | Source Codeshared String removeTerminal(String postfix) |
repeat | Source Codeshared actual String repeat(Integer times) Returns a string formed by repeating this string
the given number of |
replace | Source Codeshared String replace(String substring, String replacement) Returns a string formed by replacing every
occurrence in this string of the given nonempty
Parameters:
Throws
|
replaceFirst | Source Codeshared String replaceFirst(String substring, String replacement) Returns a string formed by replacing the first
occurrence in this string of the given nonempty
Parameters:
Throws
Since 1.1.0 |
replaceLast | Source Codeshared String replaceLast(String substring, String replacement) Returns a string formed by replacing the last
occurrence in this string of the given nonempty
Parameters:
Throws
Since 1.1.0 |
shorterThan | Source Codeshared actual Boolean shorterThan(Integer length) |
slice | Source Codeshared actual String[2] slice(Integer index) Return two strings, the first containing the
characters that occur before the given Refines List.slice |
smallerThan | Source Codeshared actual Boolean smallerThan(String other) Determines if this string occurs before the given
string in lexicographic order, returning Refines Comparable.smallerThan |
span | Source Codeshared actual String span(Integer from, Integer to) A string containing the characters of this string occurring between the given indexes. If the start index is the same as the end index, return a string with a single character. If the start index is larger than the end index, return the characters in the reverse order from the order in which they occur in this string. If both the start index and the end index are larger than the last index in the string, or if both the start index and the end index are smaller than the first index in the string, return the empty string. Otherwise, if the last index is larger than the last index in the string, return all characters from the start index to last character of the string. Using the span operator,
|
spanFrom | Source Codeshared actual String spanFrom(Integer from) A string containing the characters of this string from the given start index inclusive to the end of the string. If the start index is larger than the last index of the string, return the empty string. If the start index is negative, return this string. Using the span operator,
|
spanTo | Source Codeshared actual String spanTo(Integer to) A string containing the characters of this string from the start of the string up to and including the given end index. If the end index is negative, return the empty string. If the end index is larger than the last index in this string, return this string. Using the span operator,
|
split | Source Codeshared {String+} split(Boolean splitting(Character ch) = ..., Boolean discardSeparators = true, Boolean groupSeparators = true, Integer? limit = null) Split the string into tokens, using the given predicate function to determine which characters are separator characters delimiting token boundaries. value pathElements = path.split('/'.equals); The flags
The "foo bar baz fum".split { limit = 2; } produces the stream If the first character of this string is a
separator character, the stream begins with an
empty token. Likewise, if the last character of
this string is a separator character, and the
Note that for the case of the empty string, "".split('/'.equals) evaluates to the nonempty stream Parameters:
|
startsWith | Source Codeshared actual Boolean startsWith(List<Anything> substring) Determines if this string starts with the
characters of the given string or list. Returns
Parameters:
Refines List.startsWith |
sublist | Source Codeshared actual List<Character> sublist(Integer from, Integer to) A sublist of this list, starting at the element with
index This is a lazy operation, returning a view of this list. Refines List.sublist |
sublistFrom | Source Codeshared actual List<Character> sublistFrom(Integer from) A sublist of this list, starting at the element with the given index. This is a lazy operation, returning a view of this list. Refines List.sublistFrom |
sublistTo | Source Codeshared actual List<Character> sublistTo(Integer to) A sublist of this list, ending at the element with the given index. This is a lazy operation, returning a view of this list. Refines List.sublistTo |
substring | Source Codeshared String substring(Integer from = 0, Integer end = ...) A string containing the characters of this string beginning at the given start index, up to, but not including, the given end index. If the given end index is greater than the last index of this string, return the portion of the string from the given start index until the end of the string. If the start index is larger than the last index of the string, or if the end index is less than one or less than the start index, return the empty string. For every pair of indexes, string.substring(start, end) == string[start:end-start] Note: this operation is provided to ease migration
of code written in other languages. It is more
idiomatic to use Parameters:
Since 1.3.0 |
sum | Source Codeshared static String sum({String*} strings) The concatenation of the given See also StringBuilder |
terminal | Source Codeshared actual String terminal(Integer length) Select the last characters of the string, returning
a string no longer than the given Refines List.terminal |
trim | Source Codeshared actual String trim(Boolean trimming(Character element)) A string containing the characters of this string, after discarding the characters matching the given predicate function from the beginning and end of the string. value trimmed = name.trim('_'.equals); A character is removed from the string if it matches the given predicate and if either:
Parameters: Refines List.trim |
trimLeading | Source Codeshared actual String trimLeading(Boolean trimming(Character element)) A string containing the characters of this string, after discarding the characters matching the given predicate function from the beginning of the string. A character is removed from the string if it matches the given predicate and every character occurring earlier in the string also matches the predicate. Parameters: Refines List.trimLeading |
trimTrailing | Source Codeshared actual String trimTrailing(Boolean trimming(Character element)) A string containing the characters of this string, after discarding the characters matching the given predicate function from the end of the string. A character is removed from the string if it matches the given predicate and every character occurring later in the string also matches the predicate. Parameters: Refines List.trimTrailing |