NameTypeDescription
Returns the String of that one character, or nothing when the point names none.
Example
Taught on: Programs and values and Strings.
At a glance
- Declared
namespace String for String- Conforms to
- Refinements
type NonEmptyString = String where @::hasCharacters()A String proven to have a character in it, as a checked refinement ofString.type Character = String where @::isOneCharacter()A String of one character, as a checked refinement ofString.
- Modes
SideWhich end of a String a Method works on: the start, the end, or both ends.CaseSensitivityWhether a String comparison treats upper and lower case as the same.NormalizationFormWhich Unicode normalization formnormalize(as:)produces.
Creating
of
on String
Builds a String out of Unicode code points.
A point that names no character answers nothing. A surrogate names none, and neither does a point past the last one Unicode gives.
A point known while the Program is being written is a \u{…} escape instead. The escape character is written "\u{1B}", and answers a String rather than an Optional<String>. These entries are for a point worked out while the Program runs.
Builds a String out of a List of Unicode code points.
One point that names no character refuses the whole List. A String missing the characters it could not read is a String no caller asked for. An empty List answers the empty String.
NameTypeDescription
codePoints
List<Integer>the code points to readReturns the String of those characters, or nothing when a point names none.
Example
Equality, ordering and printing
is
on String
Answers whether the String has the same characters as another one.
The comparison is case-sensitive unless a CaseSensitivity says otherwise.
NameTypeDescription
_
Stringthe String to compare againstReturns true when the Strings are equal.
Example
NameTypeDescription
_
Stringthe String to compare againstReturns true when the Strings are equal under the given CaseSensitivity.
Example
compare
on String
Orders the String against another one, by character code point.
A CaseSensitivity of #Insensitive folds the case first.
NameTypeDescription
to
Stringthe String to order againstReturns Ordering#Less, Ordering#Equal or Ordering#Greater.
Example
NameTypeDescription
to
Stringthe String to order againstReturns Ordering#Less, Ordering#Equal or Ordering#Greater.
Example
toString
on String
Answers the String itself.
Returns the String, unchanged.
Example
isNot
on String · provided by Equatable
Answers whether the values differ.
NameTypeDescription
_
Stringthe value to compare withReturns true when the values differ.
Example
Comparing
isLessThan
on String · provided by Comparable
Answers whether the value is strictly below another.
NameTypeDescription
_
Stringthe value to compare withReturns true when the value is below the given one.
Example
isLessThanOrEqualTo
on String · provided by Comparable
Answers whether the value is below another, or equal to it.
NameTypeDescription
_
Stringthe value to compare withReturns true when the value is below the given one or equal to it.
Example
isGreaterThan
on String · provided by Comparable
Answers whether the value is strictly above another.
NameTypeDescription
_
Stringthe value to compare withReturns true when the value is above the given one.
Example
isGreaterThanOrEqualTo
on String · provided by Comparable
Answers whether the value is above another, or equal to it.
NameTypeDescription
_
Stringthe value to compare withReturns true when the value is above the given one or equal to it.
Example
Testing content
isEmpty
on String
Answers whether the String has no characters.
Returns true for the empty String, and false otherwise.
Example
hasCharacters
on String
Answers whether the String has at least one character.
Returns true when the String is not empty.
Example
isOneCharacter
on String
Answers whether the String is one character long.
This is the question the Character Type is written on. A String proven to answer true here goes wherever a Character is wanted.
Returns true when the String holds one character.
Example
hasOnlyDigits
on String
Answers whether every character of the String is a decimal digit.
A digit is any Unicode decimal digit, which is wider than what Integer.parse reads: Integer.parse reads the notation the language writes. The empty String answers true, because nothing in it is not a digit.
Returns true when the String holds decimal digits alone.
Example
hasOnlyLetters
on String
Answers whether every character of the String is a letter.
A combining mark counts as part of the letter before it. A mark standing on its own belongs to no letter and answers false. The empty String answers true.
Returns true when the String holds letters alone.
Example
hasOnlyLettersOrDigits
on String
Answers whether every character of the String is a letter or a decimal digit.
A combining mark counts as part of the character before it. The empty String answers true.
Returns true when the String holds letters and digits alone.
Example
hasOnlyWhitespace
on String
Answers whether every character of the String is whitespace.
Whitespace is what Unicode calls whitespace, which is the rule trim and words read. The empty String answers true.
Returns true when the String holds whitespace alone.
Example
Searching
contains
on String
Answers whether the given String occurs anywhere in this one.
The empty String occurs in every String. The search is case-sensitive unless a CaseSensitivity says otherwise.
Example
NameTypeDescription
_
Stringthe String to look forReturns true when it occurs.
Returns true when it occurs under the given CaseSensitivity.
doesNotContain
on String
Answers whether the given String occurs nowhere in this one.
NameTypeDescription
_
Stringthe String to look forReturns true when it does not occur.
Example
Returns true when it does not occur under the given CaseSensitivity.
Example
starts
on String
Answers whether the String begins with the given one.
Example
NameTypeDescription
with
Stringthe String to look for at the frontReturns true when the String begins with it.
NameTypeDescription
with
Stringthe String to look for at the frontReturns true when the String begins with it under the given CaseSensitivity.
doesNotStart
on String
Answers whether the String does not begin with the given one.
NameTypeDescription
with
Stringthe String to look for at the frontReturns true when the String does not begin with it.
Example
NameTypeDescription
with
Stringthe String to look for at the frontReturns true when the String does not begin with it under the given CaseSensitivity.
Example
ends
on String
Answers whether the String ends with the given one.
NameTypeDescription
with
Stringthe String to look for at the endReturns true when the String ends with it.
Example
NameTypeDescription
with
Stringthe String to look for at the endReturns true when the String ends with it under the given CaseSensitivity.
Example
doesNotEnd
on String
Answers whether the String does not end with the given one.
NameTypeDescription
with
Stringthe String to look for at the endReturns true when the String does not end with it.
Example
NameTypeDescription
with
Stringthe String to look for at the endReturns true when the String does not end with it under the given CaseSensitivity.
Example
firstIndex
on String
Answers the position of the first occurrence of the given String.
The empty String occurs at position 0. A String that does not occur answers nothing, and the defaultingTo: entry answers the given position instead.
NameTypeDescription
of
Stringthe String to look forReturns the zero-based position, or nothing when it does not occur.
Example
NameTypeDescription
of
Stringthe String to look fordefaultingTo
Integerthe position to answer with when the String does not occurReturns the zero-based position, or the given one in its place.
Example
NameTypeDescription
of
Stringthe String to look forReturns the zero-based position, or nothing when it does not occur under the given CaseSensitivity.
Example
lastIndex
on String
Answers the position of the last occurrence of the given String.
The occurrence can overlap an earlier one: "aaa"::lastIndex(of "aa") is 1. The empty String occurs at the length. A String that does not occur answers nothing, and the defaultingTo: entry answers the given position instead.
NameTypeDescription
of
Stringthe String to look forReturns the zero-based position, or nothing when it does not occur.
Example
NameTypeDescription
of
Stringthe String to look fordefaultingTo
Integerthe position to answer with when the String does not occurReturns the zero-based position, or the given one in its place.
Example
NameTypeDescription
of
Stringthe String to look forReturns the zero-based position, or nothing when it does not occur under the given CaseSensitivity.
Example
everyIndex
on String
Answers the position of every occurrence of the given String.
The occurrences do not overlap, which is the rule count(of:) counts by. The empty String occurs at no position.
NameTypeDescription
of
Stringthe String to look forReturns the List of zero-based positions, in the order they occur.
Example
count
on String
Answers how many times the given String occurs in this one.
The occurrences do not overlap: "aaa"::count(of "aa") is 1. The empty String occurs 0 times.
NameTypeDescription
of
Stringthe String to countReturns the number of occurrences, which is never negative.
Example
Returns the number of occurrences under the given CaseSensitivity, which is never negative.
Example
Reading
lines
on String
Answers the lines of the String, split at every line break.
A line break is \n, \r or \r\n. A trailing break leaves a final empty line. The empty String is one empty line.
Returns the List of lines, without the line breaks. The List always has a line in it.
Example
words
on String
Answers the words of the String.
A word is a run of characters that are not whitespace. The whitespace between the words is dropped.
Returns the List of words, empty when the String is only whitespace.
Example
length
on String
Answers how many characters the String has.
Returns the number of characters, which is never negative.
Example
on NonEmptyString
Answers how many characters the String has, which is at least one.
Returns the number of characters, which is above zero.
Example
characters
on String
Answers the characters of the String, each as its own String.
Returns the List of characters.
Example
on NonEmptyString
Answers the characters of the String, each as its own String.
Returns the List of characters, which always holds at least one.
Example
character
on String
Answers the character at the given position, counting from zero.
A negative position counts back from the end: -1 is the last character. A position outside the String answers nothing, and the defaultingTo: entry answers the given character instead.
NameTypeDescription
at
Integerthe position to readReturns the character, or nothing when the position is outside the String.
Example
NameTypeDescription
at
Integerthe position to readReturns the character, or the given one in its place.
Example
firstCharacter
on String
Answers the first character of the String.
The empty String has no first character and answers nothing. The defaultingTo: entry answers the given character instead.
Returns the first character, or nothing when the String is empty.
Example
NameTypeDescription
Returns the first character, or the given one in its place.
Example
on NonEmptyString
Answers the first character of the String.
The String has a character in it, so there is a first one to answer.
Returns the first character.
Example
lastCharacter
on String
Answers the last character of the String.
The empty String has no last character and answers nothing. The defaultingTo: entry answers the given character instead.
Returns the last character, or nothing when the String is empty.
Example
NameTypeDescription
Returns the last character, or the given one in its place.
Example
on NonEmptyString
Answers the last character of the String.
The String has a character in it, so there is a last one to answer.
Returns the last character.
Example
codePoints
on String
Answers the Unicode code points of the String.
A character is a grapheme cluster and a code point is one point of Unicode. The two counts differ wherever a character is built out of several points. A four-person emoji is one character and seven points.
Returns the List of code points, read off the composed form.
Example
Building
prepend
on String
Joins another String onto the front of this one.
NameTypeDescription
_
Stringthe String to add to the frontReturns the two Strings joined together.
Example
append
on String
Joins another String onto the end of this one.
NameTypeDescription
_
Stringthe String to add to the endReturns the two Strings joined together.
Example
repeat
on String
Answers the String joined to itself the given number of times.
NameTypeDescription
times
Integerhow many copies to joinReturns the repeated String. A count below one answers the empty String.
Example
on NonEmptyString
Answers the String joined to itself the given number of times.
The count is above zero, so the answer holds at least one copy of a String that has a character.
NameTypeDescription
Returns the repeated String, which is never empty.
Example
pad
on String
Answers the String padded with the given String up to the given length.
The padding goes at the front when no end is named. #BothEnds centres the String.
NameTypeDescription
to
Integerthe length to reachwith
String = " "the String to pad with, repeated as needed; a space when it is left out.Returns the padded String; unchanged when it is already that long.
Example
indent
on String
Answers the String with every line moved in by the given depth.
A line that is empty is left as it is, so no line gains whitespace that carries no text. The answer joins the lines with a line feed, whichever line break the String was written with.
NameTypeDescription
by
Integerhow many units to move each line in bywith
String = " "the unit to move by, repeated as needed; two spaces when it is left outReturns the indented String.
Example
separate
on String
Answers the String with a separator put in every so many characters.
The separator goes between the groups and never at either end. A String no longer than one group answers itself.
NameTypeDescription
with
Stringthe separator to put between the groupsReturns the grouped String.
Example
Cutting
split
on String
Splits the String at every occurrence of the given separator.
join(with:) on the answer rebuilds the String. A separator with a character in it always leaves at least one piece, and the entry taking a proven separator answers that.
NameTypeDescription
on
Stringthe separator to split atReturns the List of pieces, without the separator.
Example
Splits the String at every occurrence of a separator proven to have a character.
Such a separator cuts between the pieces, and the piece before the first cut is always there. So the answer is never empty.
NameTypeDescription
Returns the List of pieces, which always holds at least one.
Example
Splits the String at the first occurrence of the given separator.
The two pieces are the text before the separator and all the text after it. A separator that does not occur answers nothing. The empty separator occurs at the front, so it answers the empty String and the whole receiver.
NameTypeDescription
onFirst
Stringthe separator to cut atReturns the text before and after the separator, or nothing when it does not occur.
Example
Splits the String at the last occurrence of the given separator.
The two pieces are the text before the separator and all the text after it. A separator that does not occur answers nothing. The empty separator occurs at the end, so it answers the whole receiver and the empty String.
NameTypeDescription
onLast
Stringthe separator to cut atReturns the text before and after the separator, or nothing when it does not occur.
Example
Splits the String at the separator, into no more than the given number of pieces.
The last piece keeps every separator the split stopped short of. A count of one answers the receiver alone.
NameTypeDescription
Returns the List of pieces, which always holds at least one.
Example
trim
on String
Answers the String without the whitespace around it.
The whitespace goes from both ends when no end is named.
NameTypeDescription
Returns the trimmed String.
Example
slice
on String
Answers the characters from one position up to, but not including, another.
A negative position counts back from the end, so slice(from 0, to -1) drops the last character. An empty or inverted range answers the empty String.
NameTypeDescription
from
Integer = 0the first position to include; zero when it is left out.to
Integer = @::length()the position to stop before; the length when it is left out.Returns the String of that range of characters.
Example
remove
on String
Answers the String without the given prefix or suffix.
The String comes back unchanged when it does not begin or end with the given one. The empty String is a prefix and a suffix of every String, and taking it away changes nothing.
Example
NameTypeDescription
prefix
Stringthe String to take off the frontReturns the String without that prefix.
NameTypeDescription
suffix
Stringthe String to take off the endReturns the String without that suffix.
truncate
on String
Answers the String cut down to the given length, ending with an ellipsis.
The ellipsis counts toward the length, so the answer is never longer than the length asked for. A String already that short answers itself. A length that leaves no room for the ellipsis answers the ellipsis cut to the length, and a length below one answers the empty String.
NameTypeDescription
to
Integerthe length to cut down towith
String = "…"the String to end with; a horizontal ellipsis when it is left outReturns the cut String, of that length at the most.
Example
Changing case and form
uppercase
on String
Answers the String with every character in upper case.
Example
on NonEmptyString
Answers the String with every character in upper case.
Case mapping answers a character for every character it is given, so the answer has one too.
Returns the upper-cased String, which is never empty.
Example
lowercase
on String
Answers the String with every character in lower case.
Example
on NonEmptyString
Answers the String with every character in lower case.
Case mapping answers a character for every character it is given, so the answer has one too.
Returns the lower-cased String, which is never empty.
Example
normalize
on String
Answers the String in the given Unicode normalization form.
Two Strings that look the same can then compare and read the same. The default form is the one is and compare already work in.
The two canonical forms are one text to every other Method here. They differ in the bytes Terminal.write emits, so normalize(as #DecomposedCanonical)::length() answers what length() answered before. The two compatibility forms do change the text.
NameTypeDescription
as
NormalizationForm = #ComposedCanonicalthe normalization form to produce; #ComposedCanonical when it is left out.Returns the normalized String.
Example
replaceEvery
on String
Answers the String with every occurrence of one part replaced by another.
The occurrences do not overlap. The empty String matches nowhere, so the String comes back unchanged.
NameTypeDescription
_
Stringthe String to look forwith
Stringthe String to put in its placeReturns the String with the replacements made.
Example
NameTypeDescription
_
Stringthe String to look forwith
Stringthe String to put in its placeReturns the String with the replacements made under the given CaseSensitivity.
Example
replaceFirst
on String
Answers the String with the first occurrence of one part replaced by another.
The empty String matches nowhere, so it and a part that does not occur leave the String unchanged.
NameTypeDescription
_
Stringthe String to look forwith
Stringthe String to put in its placeReturns the String with the first replacement made.
Example
NameTypeDescription
_
Stringthe String to look forwith
Stringthe String to put in its placeReturns the String with the first replacement made under the given CaseSensitivity.
Example
reverse
on String
Answers the String with its characters in the opposite order.
Example
on NonEmptyString
Answers the String with its characters in the opposite order.
Reversing keeps every character, so the answer has one too.
Returns the reversed String, which is never empty.
Example
capitalize
on String
Answers the String with its first character in upper case.
Every other character is left as it stands. The empty String answers itself.
Returns the String with an upper-case first character.
Example
quote
on String
Answers the String as a Program would write it down.
The text is put in quotes, and anything a String Literal has to escape is escaped. A character with no spelling of its own is written as its code point.
Returns the quoted String.
Example
Refinements
Each type below is a checked refinement: a type with a condition. A value has the type only once the compiler knows the condition holds, and Checked refinements shows how it finds out. Under each one, Tighter here lists the methods above that return a more precise type when called on it. Returned by lists the methods that return it.
NonEmptyString
A String proven to have a character in it, as a checked refinement of String.
The proof is what lets length answer above zero, and firstCharacter and lastCharacter answer a character rather than an Optional. A String written down with a character in it carries the proof. A String a Program is handed earns it through an if asking hasCharacters, or the else of one asking isEmpty.
split(on:) reads the proof on its separator rather than on the receiver. A separator with a character in it always leaves a piece, so the answer is a NonEmptyList.
Tighter here length, characters, firstCharacter, lastCharacter, repeat, uppercase, lowercase, reverse
Returned by NonEmptyString::uppercase(), NonEmptyString::lowercase(), NonEmptyString::reverse(), NonEmptyString::repeat(times:)
Character
A String of one character, as a checked refinement of String.
A character is a Unicode grapheme cluster, which is the unit every position Method here counts. The proof is what lets characters and character(at:) name what they answer. A String written down with one character in it carries the proof.
A Character is a String, so it answers everything a String answers and goes wherever a String is wanted.
Returned by String::characters(), String::character(at:), String::character(at:defaultingTo:), String::firstCharacter(), String::firstCharacter(defaultingTo:), String::lastCharacter(), String::lastCharacter(defaultingTo:), NonEmptyString::characters(), NonEmptyString::firstCharacter(), NonEmptyString::lastCharacter()
Modes
Each mode below is a choice whose cases carry no payload. You pass one to a method to choose how the method works. Every mode has is, isNot and toString, and cases() on its name lists its cases, as in Side.cases(). None of them is written out for a mode: Protocols says where each one comes from.
Side
Which end of a String a Method works on: the start, the end, or both ends.
trim works on both ends when a call names no side, and pad works on the start.
Cases #Start, #End, #BothEnds
Taken by
List::pad(to:with:at:), default#EndString::trim(at:), default#BothEndsString::pad(to:with:at:), default#StartString::separate(every:with:from:), default#End
CaseSensitivity
Whether a String comparison treats upper and lower case as the same.
#Sensitive tells the two apart, and #Insensitive does not. A comparison that names no sensitivity is sensitive.
Cases #Sensitive, #Insensitive
Taken by
String::is(_:comparing:)String::compare(to:comparing:)String::contains(_:comparing:)String::doesNotContain(_:comparing:)String::starts(with:comparing:)String::doesNotStart(with:comparing:)String::ends(with:comparing:)String::doesNotEnd(with:comparing:)String::firstIndex(of:comparing:)String::lastIndex(of:comparing:)String::count(of:comparing:)String::replaceEvery(_:with:comparing:)String::replaceFirst(_:with:comparing:)
NormalizationForm
Which Unicode normalization form normalize(as:) produces.
The canonical forms, NFC and NFD, keep the text as it reads. Composed joins a base and its marks, and Decomposed splits them apart. The compatibility forms, NFKC and NFKD, also fold ligatures and superscripts onto plain equivalents, which changes the text.
Cases #ComposedCanonical, #DecomposedCanonical, #ComposedCompatibility, #DecomposedCompatibility
Taken by
String::normalize(as:), default#ComposedCanonical