Skip to main content

Text

Text in SG is UTF-8, and comes in two forms. A string owns its bytes: it can grow, and it frees them when it ends. A read string looks at text that something else owns, such as a part of a string, and copies nothing. Most methods that give back a part of a text give a read string, so trimming or splitting a line costs no allocation; the compiler checks that the look never outlives what it looks at.

Literals and escapes​

A text is written in double quotes. Inside it, \n (new line), \t (tab), \r, \0, \\, \" and \' stand for one character each, and \u{...} for the character of a code in hex:

void main() {
print("a tab:\there, a quote: \" and a backslash: \\")
print("e acute \u{e9}, a smile \u{1F600}")
print("two\nlines")
}

It prints:

a tab: here, a quote: " and a backslash: \
e acute é, a smile 😀
two
lines

Raw text​

Text between """ and """ is raw: a backslash is a backslash and a quote is a quote, which suits paths and patterns. Written over several lines, the text starts on the line after the opening quotes and ends with the line before the closing ones, and the indentation of the closing quotes is taken off every line, so the text can be indented with the code around it:

void main() {
var path = """C:\Users\pasha\"notes".txt"""
print(path)
var poem = """
Roses are red,
violets are blue.
"""
print(poem)
}

It prints:

C:\Users\pasha\"notes".txt
Roses are red,
violets are blue.

Formatted text​

$"..." puts values into a text, each in braces. A value can be any expression, and a format may follow a colon: x or X for hex, b for binary and D for decimal, each with the least number of digits, and F for a fraction with so many digits after the point. A width after a comma pads with spaces, in front, or after it when it is negative. {{ and }} write a brace.

void main() {
int n = 255
int day = 7
double price = 3.14159
var name = "Pasha"
print($"{n:x8} {n:X2} {n:b8}")
print($"{day:D3} {price:F2} {n + day}")
print($"[{name,8}] [{name,-8}] [{price,8:F2}]")
print($"{{braces}} {name.length()}")
print($"""a "quoted" {name}""")
}

It prints:

000000ff FF 11111111
007 3.14 262
[ Pasha] [Pasha ] [ 3.14]
{braces} 5
a "quoted" Pasha

A $"..." is not a string yet: print and write take it as it is and write it without making one. Where a string is needed, .toString() makes it, and that is where the allocation shows. Numbers, bool and char have .toString() too.

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

With .toString() it runs:

void main() {
int count = 3
string label = $"{count} items".toString()
string number = count.toString()
print(label)
print(number)
}

It prints:

3 items
3

Looking at text​

length() is the number of bytes. contains, startsWith and endsWith take a text or a char; indexOf and lastIndexOf give the place in bytes, or null when it is not there. trim(), trimStart() and trimEnd() give a read string, and so does a range: text[a..b], text[..b], text[a..].

void main() {
var line = " Hello, world "
var text = line.trim()
print($"[{text}] {text.length()}")
print(text.contains("world"))
print(text.startsWith("Hell"))
print(text.endsWith('d'))
print(text.indexOf('o') ?? -1)
print(text.lastIndexOf("o") ?? -1)
print(text.indexOf("xyz") ?? -1)
print(text[0..5])
print(text[7..])
print("abc" < "abd")
}

It prints:

[Hello, world] 12
true
true
true
4
8
-1
Hello
world
true

New text from old​

replaceAll, repeat, toUpper and toLower make a new string. A call of one whose result is not used is an error, since it leaves the text as it was:

void main() {
var name = "Hello, world"
print(name.replaceAll("world", "SG"))
print("ab".repeat(3))
print(name.toUpper())
print(name.toLower())
print("straße".toUpper())
}

It prints:

Hello, SG
ababab
HELLO, WORLD
hello, world
STRASSE

toUpper and toLower follow Unicode's full mappings, so ß becomes SS; no language is taken into account.

Going over text​

split (at a char or a text), splitWhitespace() and lines() give each part as a read string, with nothing copied; lines() takes off the \n or \r\n. chars() gives each char. Kept in a variable, they give one part at a time with next(), which is null at the end.

void main() {
for part in "ada,36,London".split(',') {
print(part)
}
for line in "first\nsecond\r\nthird".lines() {
print($"[{line}]")
}
long words = 0
for _ in "one two\tthree\nfour".splitWhitespace() {
words += 1
}
print(words)
var parts = "key=value".split('=')
var key = parts.next() ?? ""
var value = parts.next() ?? ""
print($"{key} -> {value}")
}

It prints:

ada
36
London
[first]
[second]
[third]
4
key -> value

Bytes and characters​

Since text is UTF-8, a character outside ASCII takes more than one byte. length() counts bytes, text[i] reads one byte, and chars() goes by characters:

void main() {
var word = "naïve"
print($"{word.length()} bytes")
int letters = 0
for c in word.chars() {
if c.isLetter() {
letters += 1
}
}
print($"{letters} letters")
print('ï'.utf8Length())
print(word[0])
print(word[0] == 'n')
}

It prints:

6 bytes
5 letters
2
110
true

A place given by indexOf is a byte place, so it can be used in a range at once. A range that would cut a character in two panics.

Building text​

A string grows at its end with write, which takes whatever print takes: a text, a number, a char, a bool, a $"...". clear() empties it and keeps its memory, and string.withCapacity(n) starts with room for n bytes, so a loop that builds a text allocates once. + and += do not join texts: their hints point to $"..." and write.

void main() {
var line = string.withCapacity(64)
for i in 1..4 {
line.write(i)
line.write(',')
}
line.write($" and {2.5:F1}")
line.write(" done")
print(line)
line.clear()
line.write(true)
print(line)
}

It prints:

1,2,3, and 2.5 done
true

Owned or borrowed​

A function that only reads a text takes it as read string; the caller lends a string with read name, and a literal goes as it is. A read string that should be kept is made a string with .clone():

nint vowels(read string text) {
nint count = 0
for c in text.chars() {
if "aeiou".contains(c) {
count += 1
}
}
return count
}

void main() {
var name = "Ada Lovelace".clone()
print(vowels(read name))
print(vowels("Grace"))
string first = name[0..3].clone()
name.clear()
print(first)
}

It prints:

5
2
Ada

name[0..3] only looks at name. Kept without .clone(), the look would still be in use when name is cleared, and the compiler refuses that:

void main() {
var name = "Ada Lovelace".clone()
var first = name[0..3]
name.clear()
print(first)
}
error: `name` cannot be changed here: `first` borrows from it and is used again later
--> example.sg:4:5
4 | name.clear()
| ^^^^
`first` borrowed it here:
--> example.sg:3:17
3 | var first = name[0..3]
| ^^^^^^^^^^
hint: finish with `first` before this line: a borrow ends at its last use

Printing first before name.clear() would be accepted too. Functions has more on read, and Ownership has the rules in full.

Numbers from text​

int.parse(text) reads a number, and the same exists on every number type. It gives a Result<int, NumberError>: Ok with the number, or an Error that is Invalid(position), the byte where the text stops being a number, or OutOfRange, when the type does not hold it. ?? gives a value for the error. parse reads a sign and digits, and for double and float a point and an exponent too; nothing else, so no spaces and no _. int.parseHex reads hex digits without 0x.

void main() {
print(int.parse("123") ?? 0)
match int.parse("12x") {
Ok(value) => print(value)
Error(why) => print(why)
}
match byte.parse("300") {
Ok(value) => print(value)
Error(why) => print(why)
}
print(double.parse("2.5e3") ?? 0.0)
print(int.parseHex("ff") ?? 0)
print(int.parse(" 1") is Error(_))
}

It prints:

123
Invalid(2)
OutOfRange
2500
255
true

What print writes for a number, parse reads back as the same number.