Text processing
std.text, padding, slicing, searching and hex conversion, because strings have no methods.
Strings have no methods. Every string operation is a function in std.text.
That is a deliberate consequence of strings being a primitive type rather than a
class, and it means you always know where to look.
std.text.format: padding, slicing, search
import { countChars, repeat, padLeft, padRight, truncate, sliceRange, tail, startsWith, endsWith, indexOf, contains, reverse, toHex, fromHex } from std.text.format
fn main() {
println(countChars("hello")) // 5
println(repeat("ab", 3)) // ababab
println(padLeft("7", 3, "0")) // 007
println(padRight("7", 3, ".")) // 7..
println(truncate("abcdef", 3)) // abc
println(sliceRange("abcdef", 1, 4)) // bcd
println(tail("abcdef", 3)) // def
println(startsWith("abcdef", "abc")) // true
println(endsWith("abcdef", "def")) // true
println(indexOf("abcdef", "cd")) // 2
println(contains("abcdef", "cd")) // true
println(reverse("abc")) // cba
println(toHex(255)) // ff
println(fromHex("ff")) // 255
}
| Function | Signature |
|---|---|
countChars |
countChars(s: string) -> int |
repeat |
repeat(s: string, count: int) -> string |
padLeft |
padLeft(s: string, width: int, fill: string) -> string |
padRight |
padRight(s: string, width: int, fill: string) -> string |
truncate |
truncate(s: string, n: int) -> string |
sliceRange |
sliceRange(s: string, lo: int, hi: int) -> string |
tail |
tail(s: string, start: int) -> string |
startsWith |
startsWith(s: string, prefix: string) -> bool |
endsWith |
endsWith(s: string, suffix: string) -> bool |
indexOf |
indexOf(s: string, sub: string) -> int |
contains |
contains(s: string, sub: string) -> bool |
reverse |
reverse(s: string) -> string |
toHex |
toHex(n: int) -> string |
fromHex |
fromHex(s: string) -> int |
There is no split, trim, replace or case mapping. splitLines lives in
std.process because line splitting is a text-stream concern, see
Processes and the environment.
std.text.stringbuilder: mutable string building
Because let is immutable, accumulating a string in a loop with += means
copying every time. StringBuilder is the mutable alternative, backed by a
List<byte>.
import { StringBuilder, builder } from std.text.stringbuilder
fn main() {
let b = StringBuilder()
b.append("hello")
b.append(", ")
b.append("world")
println(b.toString()) // hello, world
println("length {b.length()}") // 12
println("scalars {b.scalarCount()}") // 12
}
| Member | Signature | Effect |
|---|---|---|
append |
append(s: string) |
Append a string |
appendByte |
appendByte(b: byte) |
Append one byte |
appendChar |
appendChar(c: char) |
Append one scalar |
appendCp |
appendCp(cp: int) |
Append a code point |
appendInt |
appendInt(v: int) |
Append an integer |
get |
get(i: int) -> byte |
Read one byte |
set |
set(i: int, v: byte) |
Overwrite one byte |
length |
length() -> int |
Length in bytes |
scalarCount |
scalarCount() -> int |
Length in Unicode scalars |
clear |
clear() |
Discard the contents |
toString |
toString() -> string |
Materialise the string |
length counts bytes and scalarCount counts Unicode scalars, so the two
differ for any non-ASCII text. builder(seed) returns a StringBuilder
pre-filled with a string.
import { builder } from std.text.stringbuilder
fn main() {
let b = builder("start:")
b.append(" ")
b.appendInt(42)
println(b.toString()) // start: 42
}
std.text.utf8: encoding primitives
These are the low-level pieces the lexer and the string builder are built on. They work in terms of byte lists and code points.
import { cpLen, isScalar, encodeCp, encodeCpStr, scalarCount } from std.text.utf8
fn main() {
println(cpLen(0xF0)) // 4, leading byte determines the width
println(isScalar(0x2764)) // true
println(scalarCount(bytes("héllo"))) // 5
println(encodeCpStr(0x2764)) // the heart character
}
| Function | Signature |
|---|---|
cpLen |
cpLen(b0: int) -> int |
isScalar |
isScalar(cp: int) -> bool |
nextOffset |
nextOffset(bs: List<byte>, i: int) -> int |
scalarCount |
scalarCount(bs: List<byte>) -> int |
decodeCp |
decodeCp(bs: List<byte>, i: int) -> int? |
decodeStr |
decodeStr(s: string, i: int) -> int? |
encodeCp |
encodeCp(cp: int) -> List<byte> |
encodeCpStr |
encodeCpStr(cp: int) -> string |
parseUnicodeEscape |
parseUnicodeEscape(hex: string) -> int? |
unicodeEscapeStr |
unicodeEscapeStr(hex: string) -> string |
Most of these exist to serve the compiler. In application code, bytes(s),
len(s) and std.text.stringbuilder cover most needs.
Writing to the console
std.io has the four output functions, and they are the ergonomic way to print:
import { write, writeln, writeErr, writelnErr } from std.io
fn main() {
write("no newline")
writeln("")
writeln("with newline")
writeErr("to stderr")
writelnErr("")
}
| Function | Signature |
|---|---|
write |
write(text: string) -> int |
writeln |
writeln(text: string) -> int |
writeErr |
writeErr(text: string) -> int |
writelnErr |
writelnErr(text: string) -> int |
Each returns the number of bytes written, and takes a single string, build it with interpolation rather than passing several arguments.
