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.

By: Gavin

no subtypes hierarchy

Initializer
String({Character*} characters)
Parameters:
  • characters

    The characters that form this string.

Attributes
coalescedSource Codeshared actual String coalesced

This string.

emptySource Codeshared actual Boolean empty

Determines if this string has no characters, that is, if it has zero size. This is a much more efficient operation than string.size==0.

See also size
Refines Collection.empty ultimately refines Iterable.empty
firstSource Codeshared actual Character? first

The first character in the string.

Refines List.first ultimately refines Iterable.first
hashSource Codeshared actual Integer hash

A hash code for this String, computed from its UTF-16 code units.

Refines List.hash ultimately refines Object.hash
keysSource Codeshared actual Integer[] keys

A sequence containing all indexes of this string.

Refines List.keys ultimately refines Correspondence.keys
lastSource Codeshared actual Character? last

The last character in the string.

Refines List.last ultimately refines Iterable.last
lastIndexSource Codeshared actual Integer? lastIndex

The index of the last character in the string, or null if the string has no characters. Note that this operation is potentially costly for long strings, since the underlying representation of the characters uses a UTF-16 encoding. For any nonempty string:

string.lastIndex == string.size-1
linesSource Codeshared {String*} lines

Split the string into lines of text, discarding line breaks. Recognized line break sequences are \n and \r\n.

linesWithBreaksSource Codeshared {String*} linesWithBreaks

Split the string into lines of text with line breaks. Each line will be terminated by a line break sequence, \n or \r\n.

See also lines
lowercasedSource 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. tr-TR).

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.

normalizedSource 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.

restSource Codeshared actual String rest

The rest of the string, without its first character.

Refines List.rest ultimately refines Iterable.rest
reversedSource Codeshared actual String reversed

A string containing the characters of this string, with the characters in reverse order.

sizeSource 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 longerThan() or shorterThan() is highly recommended.

Refines List.size ultimately refines Iterable.size
stringSource Codeshared actual String string

This string.

Refines Iterable.string ultimately refines Object.string
trimmedSource Codeshared String trimmed

A string containing the characters of this string, after discarding whitespace from the beginning and end of the string.

uppercasedSource 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. tr-TR).

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.

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
anySource 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 false. For an infinite stream, this operation might not terminate.

Refines Iterable.any
cloneSource Codeshared actual String clone()

This string.

Refines List.clone ultimately refines Collection.clone
compareSource 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.

compareIgnoringCaseSource 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 x and y as equal if:

  • x == y,
  • x.uppercased == y.uppercased, or
  • x.lowercased == y.lowercased.

This defines a locale-independent collation that is incorrect in some locales.

containsSource Codeshared actual Boolean contains(Object element)

Determines if the given object is a String and, if so, if it occurs as a substring of this string, or if the object is a Character that occurs in this string. That is to say, a string is considered a Category of its substrings and of its characters.

Refines List.contains ultimately refines Category.contains
copyToSource Codeshared void copyTo(Array<Character> destination, Integer sourcePosition = 0, Integer destinationPosition = 0, Integer length = ...)

Efficiently copy the characters in the segment sourcePosition:length of this string to the segment destinationPosition:length of the given character array.

Parameters:
  • destination

    The array into which to copy the elements.

  • sourcePosition = 0

    The index of the first element in this array to copy.

  • destinationPosition = 0

    The index in the given array into which to copy the first element.

  • length = smallest(size - sourcePosition, destination.size - destinationPosition)

    The number of elements to copy.

countSource 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.

definesSource Codeshared actual Boolean defines(Integer index)

Determines if this string contains a character at the given index, that is, if 0<=index<size.

Refines List.defines ultimately refines Correspondence.defines
eachSource 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 loop:

for (word in words) {
    print(word.lowercased);
    print(word.uppercased);
}

For certain streams this method is highly efficient, surpassing the performance of for loops on the JVM. Thus, each() is sometimes preferred in highly performance-critical low-level code.

endsWithSource Codeshared actual Boolean endsWith(List<Anything> substring)

Determine if the given list occurs at the end of this list.

equalsSource Codeshared actual Boolean equals(Object that)

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.

Refines List.equals ultimately refines Object.equals
equalsIgnoringCaseSource Codeshared Boolean equalsIgnoringCase(String that)

Compare this string with the given string, ignoring the case of the characters. That is, by considering two characters x and y as equal if:

  • x == y,
  • x.uppercased == y.uppercased, or
  • x.lowercased == y.lowercased.
everySource 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 true. For an infinite stream, this operation might not terminate.

findSource Codeshared actual Character? find(Boolean selecting(Character element))

The first element of this stream which satisfies the given predicate function, if any, or null if there is no such element. For an infinite stream, this method might not terminate.

For example, the expression

(-10..10).find(Integer.positive)

evaluates to 1.

Refines List.find ultimately refines Iterable.find
findLastSource Codeshared actual Character? findLast(Boolean selecting(Character element))

The last element of this stream which satisfies the given predicate function, if any, or null if there is no such element. For an infinite stream, this method will not terminate.

For example, the expression

(-10..10).findLast(3.divides)

evaluates to 9.

Refines List.findLast ultimately refines Iterable.findLast
firstInclusionSource 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.

firstIndexWhereSource 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.

firstOccurrenceSource 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 from:length defined by the optional starting index and length.

getFromFirstSource Codeshared actual Character? getFromFirst(Integer index)

Returns the character at the given index in the string, or null if the index is before the start of the string or past the end of string. The first character in the string occurs at index zero. The last character in the string occurs at index string.size-1.

Refines List.getFromFirst ultimately refines Iterable.getFromFirst
getFromLastSource 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 null if the index falls outside the bounds of this string.

includesSource 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.

includesAtSource 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.

inclusionsSource 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.

indexesWhereSource 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.

initialSource Codeshared actual String initial(Integer length)

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.

Refines List.initial
iteratorSource Codeshared actual Iterator<Character> iterator()

An iterator for the characters of the string.

Refines List.iterator ultimately refines Iterable.iterator
joinSource Codeshared String join({Object*} objects)

Join the string representations of the given objects, using this string as a separator.

largerThanSource Codeshared actual Boolean largerThan(String other)

Determines if this value is strictly larger than the given value.

lastInclusionSource 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 0:size-from+1-sublist.size defined by the optional starting index, interpreted as a reverse index counting from the end of the list.

lastIndexWhereSource 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.

lastOccurrenceSource 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 size-length-from:length defined by the optional starting index, interpreted as a reverse index counting from the end of the list, and length.

locateSource Codeshared actual <Integer->Character>? locate(Boolean selecting(Character element))

The first element of this stream which satisfies the given predicate function, if any, together with its position in the stream, or null if there is no such element. For an infinite stream, this method might not terminate.

For example, the expression

(-10..10).locate(Integer.positive)

evaluates to 11->1.

locateLastSource Codeshared actual <Integer->Character>? locateLast(Boolean selecting(Character element))

The last element of this stream which satisfies the given predicate function, if any, together with its position in the stream, or null if there is no such element. For an infinite stream, this method might not terminate.

For example, the expression

(-10..10).locateLast(3.divides)

evaluates to 19->9.

locationsSource Codeshared actual {<Integer->Character>*} locations(Boolean selecting(Character element))

A stream producing all elements of this stream 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 { 2->-3, 5->0, 8->3 }.

Note that this method is more efficient than the alternative of applying Iterable.filter() to an Iterable.indexed stream.

longerThanSource Codeshared actual Boolean longerThan(Integer length)

Determines if this string is longer than the given length. This is a more efficient operation than string.size>length.

See also size
Refines List.longerThan ultimately refines Iterable.longerThan
measureSource 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 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.

Refines List.measure ultimately refines Ranged.measure
notLargerThanSource Codeshared actual Boolean notLargerThan(String other)

Determines if this value is smaller than or equal to the given value.

notSmallerThanSource Codeshared actual Boolean notSmallerThan(String other)

Determines if this value is larger than or equal to the given value.

occurrencesSource Codeshared actual {Integer*} occurrences(Character element, Integer from, Integer length)

The indexes in this list at which the given value occurs.

occursSource 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 from:length defined by the optional starting index and length.

occursAtSource Codeshared actual Boolean occursAt(Integer index, Character element)

Determines if the given value occurs at the given index in this list.

padSource Codeshared String pad(Integer size, Character character = ...)

Pad this string with the given character, producing a string of the given minimum size, centering the string.

Parameters:
  • character = ' '

    The padding character

padLeadingSource Codeshared String padLeading(Integer size, Character character = ...)

Left pad this string with the given character, producing a string of the given minimum size.

Parameters:
  • character = ' '

    The padding character

padTrailingSource Codeshared String padTrailing(Integer size, Character character = ...)

Right pad this string with the given character, producing a string of the given minimum size.

Parameters:
  • character = ' '

    The padding character

plusSource Codeshared actual String plus(String other)

Returns the concatenation of this string with the given string.

reduceSource Codeshared actual Result|Character|Null reduce<Result>(Result accumulating(Result|Character partial, Character element))

Beginning with the Iterable.first element of this stream, apply the given combining function to each element of this stream in turn, progressively accumulating a single result.

For an empty stream, reduce() always returns null.

For a stream with one element, reduce() returns that element:

{ first }.reduce(f) == first

For a given stream it with more than one element, and combining function f, the result of reduce() is obtained according to the following recursive definition:

it.reduce(f) == f(it.exceptLast.reduce(f), it.last)

For example, the expression

(1..100).reduce(plus)

results in the integer 5050.

repeatSource Codeshared actual String repeat(Integer times)

Returns a string formed by repeating this string the given number of times, or the empty string if times<=0.

Refines List.repeat ultimately refines Iterable.repeat
replaceSource Codeshared String replace(String substring, String replacement)

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.

replaceFirstSource Codeshared String replaceFirst(String substring, String replacement)

Returns a string formed by replacing the first occurrence in this string of the given substring, if any, with the given replacement string.

replaceLastSource Codeshared String replaceLast(String substring, String replacement)

Returns a string formed by replacing the last occurrence in this string of the given substring, if any, with the given replacement string.

shorterThanSource Codeshared actual Boolean shorterThan(Integer length)

Determines if this string is shorter than the given length. This is a more efficient operation than string.size>length.

See also size
Refines List.shorterThan ultimately refines Iterable.shorterThan
sliceSource Codeshared actual String[2] slice(Integer index)

Return two strings, the first containing the characters that occur before the given index, the second with the characters that occur after the given index. If the given index is outside the range of indices of this string, one of the returned strings will be empty.

Refines List.slice
smallerThanSource Codeshared actual Boolean smallerThan(String other)

Determines if this value is strictly smaller than the given value.

spanSource 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.

Refines List.span ultimately refines Ranged.span
spanFromSource 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.

Refines List.spanFrom ultimately refines Ranged.spanFrom
spanToSource 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.

Refines List.spanTo ultimately refines Ranged.spanTo
splitSource 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 discardSeparators and groupSeparators determine how separator characters should occur in the resulting stream.

Note that for the case of the empty string, split() always produces a stream containing a single empty token. For example:

"".split('/'.equals)

evaluates to the nonempty stream { "" }.

Parameters:
  • splitting = ch.whitespace

    A predicate that determines if a character is a separator characters at which to split. Default to split at any whitespace character.

  • discardSeparators = true

    Specifies that the separator characters occurring in the string should be discarded. If false, they will be included in the resulting iterator.

  • groupSeparators = true

    Specifies that the separator tokens should be grouped eagerly and not be treated as single-character tokens. If false each separator token will be of size 1.

startsWithSource Codeshared actual Boolean startsWith(List<Anything> substring)

Determine if the given list occurs at the start of this list.

sublistFromSource 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.

sublistToSource 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.

terminalSource Codeshared actual String terminal(Integer length)

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.

trimSource 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:

  • every character occurring earlier in the string also matches the predicate, or
  • every character occurring later in the string also matches the predicate.
Parameters:
  • trimming

    The predicate function that determines whether a character should be trimmed

Refines List.trim
trimLeadingSource 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:
  • trimming

    The predicate function that determines whether a character should be trimmed

trimTrailingSource 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:
  • trimming

    The predicate function that determines whether a character should be trimmed

Inherited Methods
Methods inherited from: Object
Methods inherited from: Category<Element>
Methods inherited from: Collection<Element>
Methods inherited from: Comparable<Other>
Methods inherited from: Correspondence<Key,Item>
Methods inherited from: Iterable<Element,Absent>
Methods inherited from: List<Element>
Methods inherited from: Ranged<Index,Element,Subrange>
Methods inherited from: SearchableList<Element>
Methods inherited from: Summable<Other>