A string of characters. Each character in the string is a 32-bit Unicode character. The internal UTF-16 encoding 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 encoding,
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
Initializer |
String({Character*} characters) Parameters:
|
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 The hash value of the value, which allows the value to be an element of a hash-based set or key of a hash-based map. Implementations must respect the constraint that:
Therefore, a class which refines |
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 |
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 |
lowercased | Source Codeshared String lowercased This string, with all characters in lowercase. |
normalized | Source Codeshared String normalized A string containing the characters of this string after collapsing strings of whitespace 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() |
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. |
Inherited Attributes |
Attributes inherited from: Collection<Element> |
Attributes inherited from: Correspondence<Key,Item> |
Attributes inherited from: Iterable<Element,Absent> |
Attributes inherited from: List<Element> |
Methods | |
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. Refines Comparable.compare |
contains | Source Codeshared actual Boolean contains(Object element) Determines if the given object is a |
defines | Source Codeshared actual Boolean defines(Integer index) Determines if this string contains a character at the
given |
endsWith | Source Codeshared actual Boolean endsWith(List<Anything> substring) Determine if the given list occurs at the end of this list. Refines List.endsWith |
equals | Source Codeshared actual Boolean equals(Object that) Determines if the given object is a |
firstInclusion | Source Codeshared actual Integer? firstInclusion(List<Anything> sublist) The first index in this list at which the given list occurs as a sublist. Refines List.firstInclusion |
firstOccurrence | Source Codeshared actual Integer? firstOccurrence(Anything element) The first index in this list at which the given
Refines List.firstOccurrence |
getFromFirst | Source Codeshared actual Character? getFromFirst(Integer index) Returns the character at the given |
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
Refines List.getFromLast |
includes | Source Codeshared actual Boolean includes(List<Anything> sublist) Determine if the given list occurs as a sublist at some index in this list. Refines List.includes |
includesAt | Source Codeshared actual Boolean includesAt(Integer index, List<Anything> sublist) Determine if the given list occurs as a sublist at the given index of this list. Refines List.includesAt |
inclusions | Source Codeshared actual {Integer*} inclusions(List<Anything> sublist) The indexes in this list at which the given list occurs as a sublist. Refines List.inclusions |
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 value is strictly larger than the given value. Refines Comparable.largerThan |
lastInclusion | Source Codeshared actual Integer? lastInclusion(List<Anything> sublist) The last index in this list at which the given list occurs as a sublist. Refines List.lastInclusion |
lastOccurrence | Source Codeshared actual Integer? lastOccurrence(Anything element) The last index in this list at which the given
Refines List.lastOccurrence |
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 |
notLargerThan | Source Codeshared actual Boolean notLargerThan(String other) Determines if this value is smaller than or equal to the given value. Refines Comparable.notLargerThan |
notSmallerThan | Source Codeshared actual Boolean notSmallerThan(String other) Determines if this value is larger than or equal to the given value. Refines Comparable.notSmallerThan |
occurs | Source Codeshared actual Boolean occurs(Anything element) Determines if the given value occurs as an element of this list. Refines List.occurs |
occursAt | Source Codeshared actual Boolean occursAt(Integer index, Anything element) Determines if the given value occurs at the given index in this list. Refines List.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. Refines Summable.plus |
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 |
replaceFirst | Source Codeshared String replaceFirst(String substring, String replacement) Returns a string formed by replacing the first
occurrence in this string of the given |
replaceLast | Source Codeshared String replaceLast(String substring, String replacement) Returns a string formed by replacing the last
occurrence in this string of the given |
shorterThan | Source Codeshared actual Boolean shorterThan(Integer length) |
slice | Source Codeshared actual [String, String] 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 value is strictly smaller than the given value. Refines Comparable.smallerThan |
span | Source Codeshared actual String span(Integer from, Integer to) A string containing the characters of this string 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 appear 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. |
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. |
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. |
split | Source Codeshared {String*} split(Boolean splitting(Character ch) = ..., Boolean discardSeparators = true, Boolean groupSeparators = true) Split the string into tokens, using the given predicate function to determine which characters are separator characters. value pathElements = path.split('/'.equals); The flags Parameters:
|
startsWith | Source Codeshared actual Boolean startsWith(List<Anything> substring) Determine if the given list occurs at the start of this list. Refines List.startsWith |
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 elem)) 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:
Refines List.trim |
trimLeading | Source Codeshared actual String trimLeading(Boolean trimming(Character elem)) 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. Refines List.trimLeading |
trimTrailing | Source Codeshared actual String trimTrailing(Boolean trimming(Character elem)) 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. Refines List.trimTrailing |