moduleceylon.language1.0.0
Source Code
ceylon.language
classString
OverviewPackageAttributesInitializerMethods
Type Hierarchy:
Satisfied Interfaces: Category, Cloneable<List<Element>>, Collection<Element>, Comparable<String>, Correspondence<Integer,Element>, Iterable<Element,Null>, List<Character>, Ranged<Integer,String>, Summable<String>

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 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 segment() require iteration from the beginning of the string to the given index.

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

    The characters that form this string.

Attributes
charactersSource Code
shared {Character*} characters

The characters that form this string.

coalescedSource Code
shared actual String coalesced

Returns this string.

Refined declaration: coalesced
emptySource Code
shared actual Boolean empty

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

See also: size
Refined declaration: empty
hashSource 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 x==y then x.hash==y.hash.

Refined declaration: hash
lastIndexSource Code
shared 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.

Refined declaration: lastIndex
linesSource Code
shared {String*} lines

Split the string into lines of text.

lowercasedSource Code
shared String lowercased

This string, with all characters in lowercase.

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

restSource Code
shared actual String rest

The rest of the string, without the first element.

Refined declaration: rest
reversedSource Code
shared actual String reversed

This string, with the characters in reverse order.

Refined declaration: reversed
sizeSource 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
stringSource Code
shared actual String string

Returns the string itself.

Refined declaration: string
trimmedSource Code
shared String trimmed

This string, after discarding whitespace from the beginning and end of the string.

uppercasedSource Code
shared String uppercased

This string, with all characters in uppercase.

Inherited Attributes
Attributes inherited from: Cloneable<Clone>
clone
Attributes inherited from: Collection<Element>
string
Attributes inherited from: Correspondence<Key,Item>
keys
Attributes inherited from: Iterable<Element,Absent>
coalesced, cycled, empty, first, indexed, last, rest, sequence, size, string
Attributes inherited from: List<Element>
hash, lastIndex, reversed
Methods
compareSource Code
shared actual Comparison compare(String other)

Compare this string with the given string lexicographically, according to the Unicode values of the characters.

Refined declaration: compare
containsSource Code
shared 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.

Refined declaration: contains
equalsSource Code
shared 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.

Refined declaration: equals
getSource Code
shared actual Character? get(Integer index)

Returns the character at the given index in the string, or null if the index is 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.

Refined declaration: get
initialSource Code
shared 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.

Refined declaration: initial
iteratorSource Code
shared actual Iterator<Character> iterator()

An iterator for the characters of the string.

Refined declaration: iterator
joinSource Code
shared String join({String*} strings)

Join the given strings, using this string as a separator.

longerThanSource Code
shared 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
Refined declaration: longerThan
plusSource Code
shared actual String plus(String other)

Returns the concatenation of this string with the given string.

Refined declaration: plus
repeatSource Code
shared 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.

Refined declaration: repeat
replaceSource Code
shared 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.

segmentSource Code
shared actual String segment(Integer from, Integer length)

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
shorterThanSource Code
shared 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
Refined declaration: shorterThan
spanSource Code
shared actual String span(Integer from, Integer to)

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
spanFromSource Code
shared actual String spanFrom(Integer from)

Obtain a span containing the mapped values between the starting index and the end of the receiver.

Refined declaration: spanFrom
spanToSource Code
shared actual String spanTo(Integer to)

Obtain a span containing the mapped values between the start of the receiver and the end index.

Refined declaration: spanTo
splitSource 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:
  • 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.

terminalSource Code
shared 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.

Refined declaration: terminal
trimSource Code
shared actual String trim(Boolean trimming(Character elem))

This string, after discarding the given characters from the beginning and end of the string

Refined declaration: trim
trimLeadingSource Code
shared actual String trimLeading(Boolean trimming(Character elem))

This string, after discarding the given characters from the beginning of the string

Refined declaration: trimLeading
trimTrailingSource Code
shared actual String trimTrailing(Boolean trimming(Character elem))

This string, after discarding the given characters from the end of the string

Refined declaration: trimTrailing
Inherited Methods
Methods inherited from: Category
contains, containsAny, containsEvery
Methods inherited from: Comparable<Other>
compare
Methods inherited from: Correspondence<Key,Item>
defines, definesAny, definesEvery, get, items
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>
endsWith, equals, firstInclusion, firstOccurrence, includes, includesAt, inclusions, indexes, initial, lastInclusion, lastOccurrence, occurrences, occurs, occursAt, startsWith, terminal, trim, trimLeading, trimTrailing, withLeading, withTrailing
Methods inherited from: Ranged<Index,Span>
segment, span, spanFrom, spanTo
Methods inherited from: Summable<Other>
plus