Skip to main content

Text

A string owns its bytes, which are always valid UTF-8, and grows at its end. A read string looks at text that something else owns: a literal, a part of a string, what trim gives. Nothing is copied to make one, and the compiler checks that the text it looks at lives as long as the view. A char is one Unicode character. All three are built into the language.

Lengths and places in a text are counted in bytes, as a nint; going over the characters is chars().

Making text​

SignatureWhat it does
"...", """..."""A literal; a raw literal has no escapes
$"..."A formatted text, written where it goes without a string being made
string toString() on $"..." and on a numberThe text as a new string
string clone(read this)A copy that owns its bytes
string string.withCapacity(nint n)An empty text with room for n bytes
void write(ref this, x)Adds at the end whatever print takes
void clear(ref this)Empties the text and keeps its memory
void main() {
var name = "Ada"
var line = name.clone()
line.write(" is ")
line.write(36)
line.write('!')
print(line)

string label = $"{name}: {line.length()} bytes".toString()
print(label)

var report = string.withCapacity(64)
for i in 0..3 {
report.write($"{i};")
}
print(report)
report.clear()
print(report.length())
print("""C:\temp "quoted" text""")
}

It prints:

Ada is 36!
Ada: 10 bytes
0;1;2;
0
C:\temp "quoted" text

A formatted text is not a string by itself, so that every allocation is written where it happens:

void main() {
var name = "Ada"
string line = $"{name}"
print(line)
}
error: expected `string`; `$"..."` does not become a `string` on its own
--> example.sg:3:19
3 | string line = $"{name}"
| ^^^^^^^^^
hint: add `.toString()` at the end; that is where the allocation shows

text += "x" is an error whose hint is write, and writing a text into itself (s.write(s.trim())) is an error whose hint is .clone().

Bytes and views​

SignatureWhat it does
nint length(read this)The length in bytes
text[i]The byte at i; a panic outside the text, with the index and the length
text[a..b], text[..b], text[a..], text[..]A read string of those bytes; a panic when the range cuts a character in half
read byte[] asBytes(read this)The bytes, to look at
Result<read string, TextError> string.fromUtf8(read byte[] bytes)The bytes as text, or the place of the first byte that is not UTF-8 (cause.position)
void main() {
var word = "héllo"
print(word.length())
print(word[0])
print(word[1..3])
print(word[3..])
print("Hi".asBytes())

var bytes = List<byte> { 72, 255 }
match string.fromUtf8(read bytes) {
Ok(text) => print(text)
Error(cause) => print($"not UTF-8 at byte {cause.position}")
}
}

It prints:

6
104
é
llo
[72, 105]
not UTF-8 at byte 1

word[1..2] would stop the program: é takes the bytes 1 and 2, and a string is always valid UTF-8. text[i] = 'a' is a compile error for the same reason.

Looking inside​

SignatureWhat it does
nint? indexOf(read this, x)The place of the first x, a char, a read string or a byte, or null
nint? lastIndexOf(read this, x)The place of the last one
bool contains(read this, x)Whether x (a char or a read string) is in the text
bool startsWith(read this, x), bool endsWith(read this, x)Whether the text starts or ends with x
bool equalsIgnoreAsciiCase(read this, read string other)Equal when A-Z and a-z are taken as the same
bool equalsIgnoreCase(read this, read string other)Equal by Unicode's full case folding, with no allocation
int compare(read this, read string other), bool equals(read this, read string other)What < and == are short for: the order of the bytes
void main() {
var text = "hello, wörld"
print(text.indexOf('o') ?? -1)
print(text.lastIndexOf('o') ?? -1)
print(text.indexOf("wö") ?? -1)
print(text.indexOf('z') ?? -1)
print(text.contains("llo"))
print(text.startsWith("he") && text.endsWith('d'))
print("Content-Length".equalsIgnoreAsciiCase("content-length"))
print("STRASSE".equalsIgnoreCase("straße"))
print("abc" < "abd")
print("abc".compare("abd"))
}

It prints:

4
4
7
-1
true
true
true
true
true
-1

Parts of a text​

Each of these gives views of the text, nothing copied. A for takes the parts one by one; kept in a var, the iterator gives the next part with next(), and null at the end. While parts are in use, the text cannot be changed or moved.

SignatureWhat it gives
read string trim(read this), trimStart, trimEndThe text without the white space around it
split(read this, x)The parts between each x, a char or a read string; split("") is an error
splitWhitespace(read this)The words, apart at any Unicode white space
lines(read this)The lines, without \n or \r\n
chars(read this)Each char
void main() {
var line = " name = Ada , 36 "
print($"[{line.trim()}]")
for part in line.split(',') {
print($"<{part.trim()}>")
}
var fields = "k=v".split('=')
print(fields.next() ?? "")
print(fields.next() ?? "")
print(fields.next() ?? "none")
for word in " to be or\tnot ".splitWhitespace() {
print(word)
}
for l in "one\r\ntwo\n".lines() {
print($"[{l}]")
}
for c in "aé😀".chars() {
print($"{c} {(int)c} {c.utf8Length()}")
}
}

It prints:

[name = Ada , 36]
<name = Ada>
<36>
k
v
none
to
be
or
not
[one]
[two]
a 97 1
é 233 2
😀 128512 4

A method that only gives a value is an error when the value is not used, since it changes nothing:

void main() {
var name = " Ada "
name.trim()
print(name)
}
error: the text that `trim` gives is not used: it leaves `name` as it was
--> example.sg:3:5
3 | name.trim()
| ^^^^^^^^^^^
hint: keep it in a variable: `var text = name.trim()`

New text from text​

SignatureWhat it gives
string replaceAll(read this, old, new)Every old replaced by new, each a char or a read string
string repeat(read this, nint n)The text n times
string toUpper(read this), string toLower(read this)By Unicode's full mappings: "straße".toUpper() is "STRASSE", and Σ at the end of a word becomes ς
string foldCase(read this)The text as it is compared without case
string string.join(read string separator, read List<string> parts)The parts with the separator between them

No language is taken into account: "i".toUpper() is "I".

void main() {
print("a-b-c".replaceAll('-', ", "))
print("ab".repeat(3))
print("Straße".toUpper())
print("ΟΔΟΣ".toLower())
print("Straße".foldCase())
var names = List<string> { "ada", "grace" }
print(string.join(" and ", read names))
}

It prints:

a, b, c
ababab
STRASSE
οδος
strasse
ada and grace

Writing values into text​

Inside $"..." a width and a letter may follow a value, as in C#: {n,5} takes at least five characters with spaces in front, {n,-5} with spaces after; {n:D4} writes at least four decimal digits, {n:x} and {n:X4} hex, {n:b8} binary, {price:F2} two digits after the point; {price,8:F3} both. {{ and }} write a brace. A width counts characters, not bytes.

void main() {
var n = 42
var price = 3.14159
print($"[{n,5}] [{n,-5}] [{n:D4}] [{n:x}] [{n:X4}] [{n:b8}]")
print($"[{price:F2}] [{price,8:F3}] {{n}} [{"é",3}]")
}

It prints:

[ 42] [42 ] [0042] [2a] [002A] [00101010]
[3.14] [ 3.142] {n} [ é]

char​

A char is written 'a', 'é', '\n' or '\u{e9}'. It is not a number: (int)c gives its code and (char)n the character of a code, which panics when no character has it; n.tryToChar() gives null there. ==, <, match, print and keys of a HashMap work on it. A character of one byte, like '+', is also a byte where an integer is expected (byte b = '+', text[i] == ':').

SignatureWhat it does
bool isAsciiDigit(read this), isAsciiLetter, isAsciiAlphanumeric, isAsciiUpper, isAsciiLower, isAsciiWhitespace, isAsciiTests on ASCII, on char and on byte
toAsciiUpper(read this), toAsciiLower(read this)a-z to A-Z and back; on byte too
bool isLetter(read this), isNumeric, isAlphanumeric, isUpper, isLower, isControl, isWhitespaceUnicode 17.0's categories: L, N, L or N, Lu, Ll, Cc, and white space
char toUpper(read this), char toLower(read this)One character for one: 'ß'.toUpper() is 'ß'
nint utf8Length(read this)How many bytes the character takes in UTF-8
UnicodeCategory category(read this)Its general category in Unicode 17.0: UppercaseLetter, DecimalNumber, CurrencySymbol, ... Unassigned; abbreviation() gives the short name, Lu
void main() {
var c = 'é'
print($"{c} {(int)c} {c.utf8Length()}")
print((char)65)
print(0xD800.tryToChar() ?? '?')
print('7'.isAsciiDigit())
print('٣'.isNumeric())
print('ß'.toUpper())
print('Q'.isUpper() && 'q'.isLetter())
print($"{'€'.category()} {'€'.category().abbreviation()}")
byte b = 'x'
print(b.toAsciiUpper())
}

It prints:

é 233 2
A
?
true
true
ß
true
CurrencySymbol Sc
88

toAsciiUpper on a byte gives a byte, which prints as a number. Arithmetic on a char is refused:

void main() {
var c = 'a'
print(c + 1)
}
error: operator `+` is not defined for `char` and `int`
a `char` is not a number: `(int)c` is its code, and `(char)n` the character of a code

Reading numbers out of text is on the page Numbers.