Text processing

std.text, padding, slicing, searching and hex conversion, because strings have no methods.

vlatest

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.

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.

Next steps