A string of characters. Each character in the string is a 32-bit Unicode character. The internal UTF-16 encoding is hidden from clients.
A string is a Category
of its Character
s, 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 List
s of Character
s:
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 segment()
require iteration from the
beginning of the string to the given index.
Initializer |
String({Character*} characters) Parameters:
|
Attributes | |
characters | Source Code shared {Character*} characters The characters that form this string. |
coalesced | Source Code shared actual String coalesced Returns this string. Refined declaration: coalesced |
empty | Source Code shared actual Boolean empty |
hash | Source Code shared 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 if Refined declaration: hash |
lastIndex | Source Code shared actual Integer? lastIndex The index of the last character in the string, or
Refined declaration: lastIndex |
lines | Source Code shared {String*} lines Split the string into lines of text. |
lowercased | Source Code shared String lowercased This string, with all characters in lowercase. |
normalized | Source Code shared String normalized This string, after collapsing strings of whitespace into single space characters and discarding whitespace from the beginning and end of the string. |
rest | Source Code shared actual String rest The rest of the string, without the first element. Refined declaration: rest |
reversed | Source Code shared actual String reversed This string, with the characters in reverse order. Refined declaration: reversed |
size | Source Code shared 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. See also: longerThan, shorterThan Refined declaration: size |
string | Source Code shared actual String string Returns the string itself. Refined declaration: string |
trimmed | Source Code shared String trimmed This string, after discarding whitespace from the beginning and end of the string. |
uppercased | Source Code shared String uppercased This string, with all characters in uppercase. |
Inherited Attributes |
Attributes inherited from: Cloneable<Clone> |
Attributes inherited from: Collection<Element> |
Attributes inherited from: Correspondence<Key,Item> |
Attributes inherited from: Iterable<Element,Absent> |
Attributes inherited from: List<Element> |
Methods | |
compare | Source Code Compare this string with the given string lexicographically, according to the Unicode values of the characters. Refined declaration: compare |
contains | Source Code Determines if the given object is a Refined declaration: contains |
equals | Source Code Determines if the given object is a string, and if so, if this string has the same length, and the same characters, in the same order, as the given string. Refined declaration: equals |
get | Source Code Returns the character at the given index in the
string, or Refined declaration: get |
initial | Source Code Select the first characters of this string, returning a string no longer than the given length. If this string is shorter than the given length, return this string. Otherwise return a string of the given length. Refined declaration: initial |
iterator | Source Code An iterator for the characters of the string. Refined declaration: iterator |
join | Source Code Join the given strings, using this string as a separator. |
longerThan | Source Code Determines if this string is longer than the given
length. This is a more efficient operation than
See also: size Refined declaration: longerThan |
plus | Source Code Returns the concatenation of this string with the given string. Refined declaration: plus |
repeat | Source Code Returns a string formed by repeating this string
the given number of times, or the empty string if
Refined declaration: repeat |
replace | Source Code Returns a string formed by replacing every occurrence in this string of the given substring with the given replacement string, working from the start of this string to the end. |
segment | Source Code Select the characters of this string beginning at the given index, returning a string no longer than the given length. If the portion of this string starting at the given index is shorter than the given length, return the portion of this string from the given index until the end of this string. Otherwise return a string of the given length. If the start index is larger than the last index of the string, return the empty string. Refined declaration: segment |
shorterThan | Source Code Determines if this string is shorter than the given
length. This is a more efficient operation than
See also: size Refined declaration: shorterThan |
span | Source Code Select the characters 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, return the empty string. Otherwise, if the last index is larger than the last index in the sequence, return all characters from the start index to last character of the string. Refined declaration: span |
spanFrom | Source Code Obtain a span containing the mapped values between the starting index and the end of the receiver. Refined declaration: spanFrom |
spanTo | Source Code Obtain a span containing the mapped values between the start of the receiver and the end index. Refined declaration: spanTo |
split | Source Code shared {String*} split(Boolean splitting(Character ch) = ..., Boolean discardSeparators = true, Boolean groupSeparators = true) Split the string into tokens, using the given predicate to determine which characters are separator characters. Parameters:
|
terminal | Source Code Select the last characters of the string, returning a string no longer than the given length. If this string is shorter than the given length, return this string. Otherwise return a string of the given length. Refined declaration: terminal |
trim | Source Code This string, after discarding the given characters from the beginning and end of the string Refined declaration: trim |
trimLeading | Source Code This string, after discarding the given characters from the beginning of the string Refined declaration: trimLeading |
trimTrailing | Source Code This string, after discarding the given characters from the end of the string Refined declaration: trimTrailing |
Inherited Methods |
Methods inherited from: Category |
Methods inherited from: Comparable<Other> |
Methods inherited from: Correspondence<Key,Item> |
Methods inherited from: Iterable<Element,Absent> any, by, chain, collect, count, cycle, defaultNullElements, every, filter, find, findLast, fold, following, iterator, longerThan, map, repeat, select, shorterThan, skipping, skippingWhile, sort, taking, takingWhile |
Methods inherited from: List<Element> |
Methods inherited from: Ranged<Index,Span> |
Methods inherited from: Summable<Other> |