Axle v0.22.0

Strings and text

string is a built-in immutable UTF-8 type. Its common methods are part of the language, so basic operations need no use. The wider surface lives in std/text: parsers, builders, JSON and CSV helpers, regex, encodings, hashes, UUIDs and semantic versions.

  string  ──┬── methods on the value        s.trim(), s.indexOf("/")
            │                               (no import)
            ├── properties                  s.length, s.byteLength
            │
            └── std/text module functions   text::parseI32(s), csv::csvField(row, 0)
                                            (bind the module with use)

Equality and ordering

let a : string = "hello";
let b : string = "Hello";

if (a.equals(b))                  { /* false */ }
if (a.equalsIgnoreCase(b))        { /* true  */ }

let cmp : i32 = a.compareTo(b);   // <0, 0, >0: lexicographic, byte order

== and != on strings compare content, the same answer equals gives. Two strings built independently are equal when their bytes match. Use equals when you want the call site to read as a comparison, and equalsIgnoreCase when case must not matter. Classes are the exception: == compares their identity, so an @derive(Eq) class is where == will not do what you meant.

Length and emptiness

let s : string = "héllo";

let n : i32 = s.length;                         // 5: one per character
if (s.isEmpty()) { /* false */ }
if ("   ".isBlank())   { /* true: only whitespace */ }

.length returns the codepoint (character) count, not the byte count. é counts as one character even though it takes two bytes in UTF-8. .byteLength returns the byte count, and it is the bound a byte walk needs: .byteAt(i) reads octets, so length would stop short by the number of multi-byte characters.

let s : string = "héllo";
let chars : i32 = s.length;        // 5
let bytes : i64 = s.byteLength;    // 6

let i : i64 = 0;
while (i < s.byteLength) {
    let b : i32 = s.byteAt(i);
    i = i + 1;
}

byteLength and byteAt are O(1). A string stores its byte length in a header just before the bytes, so both are a header read. length counts codepoints and therefore scans the string.

Slicing

fn main() : i32 ! IndexOutOfBoundsException {
    let s : string = "hello world";

    let hello : string = s.substring(0, 5);      // "hello": [start, end)
    let rest  : string = s.substringFrom(6);     // "world"
    println(hello + " " + rest);
    return 0;
}

Both throw IndexOutOfBoundsException on an out-of-range index. The end of substring is exclusive.

Trimming and case

fn main() : i32 {
    println("  hello  ".trim());                 // "hello"
    println("  hello  ".trimStart());            // "hello  "
    println("  hello  ".trimEnd());              // "  hello"

    println("AxLe".toLowerCase());               // "axle"
    println("AxLe".toUpperCase());               // "AXLE"
    return 0;
}

Trimming and case folding follow Unicode, so they handle characters beyond ASCII.

fn main() : i32 {
    let path : string = "/usr/local/bin/axle";

    println(path.startsWith("/usr"));            // true
    println(path.endsWith("/axle"));             // true
    println(path.contains("local"));             // true
    println(path.indexOf("/"));                  // 0     (first match)
    println(path.lastIndexOf("/"));              // 14    (last match)
    println(path.indexOf("nope"));               // -1    (sentinel)
    return 0;
}

indexOf and lastIndexOf return -1 when the substring is absent.

Transformation

fn main() : i32 {
    println("hello, world".replace(",", ";"));   // "hello; world"
    println("ab".repeat(3));                     // "ababab"
    println("hello".reverse());                  // "olleh"
    println("foo".concat("bar"));                // "foobar"
    return 0;
}

replace substitutes every occurrence. There is no first-only variant: use indexOf and substring when you need one.

Character access

charAt(i) returns the codepoint at character index i, or -1 when i is past the end. It indexes codepoints, not bytes. For a multi-byte character, charAt(1) is the second character, whatever its byte offset. charCodeAt is the same operation under the conventional name.

let s : string = "AB";
let a : i32 = s.charAt(0);                       // 65
let b : i32 = s.charAt(1);                       // 66
let z : i32 = s.charAt(2);                       // -1

To walk codepoints, loop with charAt and your own index. The loop handles each character as an i32.

Classifying a codepoint

A codepoint is an i32, so a match with range patterns reads the character classes directly. Name the categories with an enum, and let the arms map each ASCII range to a variant:

enum CharClass {
    Digit,
    Upper,
    Lower,
    Other,
}

fn classify(c : i32) : CharClass {
    return match c {
        48..=57  => CharClass::Digit,    // '0'..'9'
        65..=90  => CharClass::Upper,    // 'A'..'Z'
        97..=122 => CharClass::Lower,    // 'a'..'z'
        _        => CharClass::Other,
    };
}

match is an expression. The _ arm makes the match exhaustive, and the named variants make a later match cls { … } read far better than comparing raw code ranges at every call site.

Padding

fn main() : i32 {
    println("42".padStart(5, 48));               // "00042" (48 = '0')
    println("42".padEnd(5, 32));                 // "42   " (32 = space)
    return 0;
}

The pad character is a Unicode codepoint, passed as an i32.

Parsing

Methods on the string parse it into a number or a boolean. Each throws ParseException when the text does not represent a value of the target type:

fn main() : i32 ! ParseException {
    let a : i32 = "42".toI32();
    let b : i64 = "1234567890123".toI64();
    let c : f64 = "3.14".toF64();
    let d : bool = "true".toBool();
    return a;
}

The same parsers exist as functions in std/text, which is handy when the text is not a receiver you hold:

use std::text;

fn readNumbers() : i32 ! ParseException {
    let n   : i32  = text::parseI32("42");
    let big : i64  = text::parseI64("1234567890123");
    let u   : u32  = text::parseU32("4000000000");
    let f   : f64  = text::parseF64("3.14");
    let b   : bool = text::parseBool("true");
    return n;
}

The integer and boolean parsers ignore surrounding Unicode whitespace.

Conversion to string

let n : i32     = 42;
let f : f64     = 3.14;
let b : bool    = true;

let s1 : string = n.toString();                   // "42"
let s2 : string = f.toString();                   // "3.14"
let s3 : string = b.toString();                   // "true"

toString() is defined on every primitive. The output takes the usual forms ("42", "3.14", "true").

Concatenation

+ on strings is left-to-right concatenation:

let name : string = "Alice";
let id   : i32    = 7;
let line : string = "user " + name + " id=" + id;
// "user Alice id=7"

+ also accepts a primitive on either side when the other operand is a string. The primitive is converted to text first:

let n  : i32    = 42;
let s  : string = "n=" + n;                       // "n=42"
let s2 : string = n + " is the answer";           // "42 is the answer"

Building strings: StringBuilder

For long iterative concatenation, use StringBuilder. Each + copies the whole growing left operand, so a loop of + costs O(n²) in total. The builder keeps one growing buffer and copies only once, at the end.

use std::collections::ArrayList;
use std::text::StringBuilder;

fn buildCsv(rows : ArrayList<i32>) : string {
    let sb : StringBuilder = new StringBuilder();
    let mut i : i32 = 0;
    while (i < rows.size()) {
        if (i > 0) {
            sb.append(",");
        }
        sb.appendI32(rows.get(i) ?? 0);     // in range: never null
        i = i + 1;
    }
    return sb.toString();
}
MethodReturnsEffect
append(s)StringBuilderappend a string
appendChar(c)StringBuilderappend a codepoint (i32)
appendI32(v) / appendI64(v)StringBuilderappend an integer
appendF64(v)StringBuilderappend a float
appendBool(v)StringBuilderappend "true" or "false"
length()i32character count
byteLength()i64byte count
isEmpty()booltrue when nothing has been appended
toString()stringa fresh owned copy of the contents; the builder stays usable
clear()StringBuilderempty the buffer for reuse
reverse()StringBuilderreverse the contents in place

Every append* method returns the builder, so calls chain:

use std::text::StringBuilder;

fn main() : i32 {
    let s : string = new StringBuilder()
        .append("[")
        .appendI32(42)
        .append(", ")
        .appendF64(3.14)
        .append("]")
        .toString();
    println(s);
    return 0;
}

toString() allocates a fresh owned string on every call. The builder keeps its buffer and stays usable, but each result is a new heap string whose ownership moves to you. Bind it or return it. A temporary that is never bound is still released, so a dropped toString() frees its allocation. A builder reused across a loop should still call toString() once, at the end, as buildCsv and join do. Calling it per iteration allocates a string each pass. Use clear() to reset the buffer without freezing it.

  sb.append("a") ─┐
  sb.append("b") ─┼─▶ one growing buffer  ──toString()──▶ one string (copied once)
  sb.appendI32(3)─┘

JSON

std/text/json has two layers. The first is pure helpers: validate a document and escape values so you can build JSON by concatenation:

use std::text::StringBuilder;
use std::text::json::jsonQuoteString;
use std::text::json::jsonValidate;

fn buildPayload(name : string, age : i32) : string {
    let sb : StringBuilder = new StringBuilder();
    sb.append("{\"name\":");
    sb.append(jsonQuoteString(name));           // produces "Alice", with the quotes
    sb.append(",\"age\":");
    sb.appendI32(age);
    sb.append("}");
    return sb.toString();
}

fn isValid(payload : string) : bool ! ParseException {
    return jsonValidate(payload);
}
FunctionReturnsEffect
jsonValidate(text)booltrue when text is a complete JSON document; throws ParseException when it nests deeper than MAX_JSON_NESTING_DEPTH
jsonQuoteString(s)strings escaped and wrapped in double quotes
jsonEscapeString(s)strings escaped, without outer quotes
jsonI64ToString(v)stringinteger as JSON text
jsonF64ToString(v)stringfloat as JSON text; NaN and infinities become null
jsonBoolToString(b)stringtrue or false
jsonNull()stringthe text null

Validation recurses, and its input is untrusted, so nesting is capped at MAX_JSON_NESTING_DEPTH. A document past the cap raises ParseException — a refusal you can catch, where descending into it would overflow the process stack and end the program.

The second layer is a cursor, Json. Json.parse validates a document once, and then each accessor reads one top-level member by key:

use std::text::json::Json;

fn readUser(body : string) : string ! ParseException {
    let doc : Json = Json::parse(body);
    if (!doc.has("name")) {
        return "anonymous";
    }
    let age : i64 = doc.int("age");         // 0 when absent
    return doc.text("name") + " (" + age.toString() + ")";
}
Json memberReturnsWhen the key is absent
Json::parse(text)Jsonthrows ParseException when text is not valid JSON
has(key)boolfalse
text(key)string""
int(key)i640
num(key)f640.0
flag(key)boolfalse

The cursor walks the document for each lookup rather than building a tree. That suits a response with a few fields read once. For a large document read many times, parse it into your own structure.

CSV rows

std/text/csv is an RFC 4180 single-row parser. It reads one row at a time, by index, and never materialises an array. Loop over the fields with csvFieldCount and csvField:

use std::text::csv;

fn main() : i32 ! IndexOutOfBoundsException {
    let row : string = "alice,\"Smith, Jr.\",42";
    let n : i32 = csv::csvFieldCount(row);       // 3: quoting-aware
    let mut i : i32 = 0;
    while (i < n) {
        println(csv::csvField(row, i));          // alice / Smith, Jr. / 42
        i = i + 1;
    }
    return 0;
}

A quoted field may contain commas, and a doubled "" inside it is a literal ". csvField(row, i) throws IndexOutOfBoundsException past the last field, so the ! clause above propagates it.

To write a row, csvEncode quotes a field only when it has to: when it contains a comma, a quote or a newline. csvJoin2 joins two already-encoded fields with a comma:

use std::text::csv;

fn main() : i32 {
    println(csv::csvEncode("plain"));          // plain: no quoting needed
    println(csv::csvEncode("has,comma"));      // "has,comma": quoted
    println(csv::csvJoin2(csv::csvEncode("a,b"), csv::csvEncode("c")));  // "a,b",c
    return 0;
}

csvJoin2 does no quoting of its own. Encode each field first, then join. Wider rows compose: csvJoin2(csvJoin2(a, b), c), or build the row with a StringBuilder, encoding each cell as you go.

FunctionReturnsEffect
csvFieldCount(row)i32number of fields in one row, quoting-aware
csvField(row, i)stringthe i-th field, unquoted; throws IndexOutOfBoundsException
csvEncode(field)stringquoted when it contains ,, " or a newline
csvJoin2(a, b)stringtwo already-encoded fields joined by a comma

A record that spans several physical lines is not supported. Split a multi-row document on "\n" first (see Splitting below), then parse each line.

Regex

std::text::regex offers a Pattern and a Matcher. Compile a Pattern once and reuse it. A Pattern holds a compiled regex, and it is Closeable, and the compiler frees it when the binding leaves scope. close() is idempotent, so defer p.close() is allowed but not required (E0511 applies only to Closeable types with no registered teardown).

use std::text::regex::Pattern;

fn extractDigits(s : string) : string ! IllegalArgumentException, IOException {
    let p : Pattern = new Pattern("[^0-9]");
    defer p.close();
    return p.replaceAll(s, "");          // strip everything that is not a digit
}

Pattern

MethodReturnsEffect
matches(s)boolwhole-string test, anchored at both ends
find(s)booltrue when the pattern occurs anywhere in s
replaceAll(s, repl)stringrewrite every match
replaceFirst(s, repl)stringrewrite the first match
split(s)stringthe pieces of s between matches, joined by \n
matcher(s)Matchera cursor over the matches of s
pattern()stringthe source the pattern was compiled from
close()voidreleases the compiled regex; throws IOException

The constructor throws IllegalArgumentException when the source is not a valid pattern.

Matcher: iterating matches and reading groups

use std::text::regex::Matcher;
use std::text::regex::Pattern;

fn firstNumber(s : string) : string ! IllegalArgumentException, IOException {
    let p : Pattern = new Pattern("([a-z]+)-([0-9]+)");
    defer p.close();
    let m : Matcher = p.matcher(s);
    if (m.find()) {
        return m.groupAt(2);             // the digits after the dash
    }
    return "";
}
Matcher methodReturnsEffect
find()booladvance to the next match; false when none is left
matches()boolwhole-input test for the current input
group()stringthe whole current match
groupAt(i)stringcapture group i; group 0 is the whole match
groupCount()i32the number of capture groups
start() / end()i32offsets of the current match
reset()voidstart scanning from the beginning again
replaceAll(repl)stringrewrite every match of the current input

The syntax is the one of the Rust regex crate. Matching runs in linear time, so a pattern cannot backtrack catastrophically, but there are no backreferences and no lookaround.

Splitting

Pattern.split cuts a string on every match and returns the pieces joined by \n. Feed that to a line-by-line consumer:

use std::text::regex::Pattern;

fn splitCsvLine(line : string) : string ! IllegalArgumentException, IOException {
    let comma : Pattern = new Pattern(",");
    defer comma.close();
    return comma.split(line);            // "a,b,c" becomes "a\nb\nc"
}

For single-character separators, a loop of indexOf and substring also works. Collect the pieces into an ArrayList<string>.

Encodings

use std::text::encoding;

fn roundTrip() : string ! ParseException, IllegalArgumentException {
    let bytes : string = encoding::base64Encode("Hello");   // "SGVsbG8="
    let plain : string = encoding::base64Decode(bytes);     // "Hello"

    let hex : string = encoding::hexEncode("AB");           // "4142"
    let back : string = encoding::hexDecode(hex);           // "AB"
    return plain;
}
FunctionReturnsNotes
base64Encode(s) / base64UrlEncode(s)stringnever fails
base64Decode(s) / base64UrlDecode(s)stringthrows ParseException on a bad symbol or invalid UTF-8, IllegalArgumentException on a decoded NUL
hexEncode(s)stringtwo hex digits per byte, never fails
hexDecode(s)stringthrows ParseException on an odd length or a non-hex digit, IllegalArgumentException on a decoded NUL

The encode direction never fails. The decode direction throws ParseException on malformed input and IllegalArgumentException when the decoded bytes hold a NUL (an Axle string cannot carry one), so base64Decode and hexDecode must sit in a function that lists both, or wrap the call in a catch.

URLs

use std::text::url;
use std::lang::ParseException;

fn main() : i32 ! ParseException {
    let escaped : string = url::urlEncode("hello world&foo=bar");
    // "hello%20world%26foo%3Dbar"

    let raw : string = url::urlDecode("a%20b");
    println(escaped + " " + raw);
    return 0;
}
FunctionReturnsEffect
urlEncode(s) / urlDecode(s)stringpercent-encoding; urlDecode throws ParseException
urlEncodeForm(s) / urlDecodeForm(s)stringthe form-encoding variant of the same pair (HTML form rules)
urlScheme(u)stringthe scheme, such as https
urlHost(u)stringthe host name
urlPort(u)i32the port number given in the URL, or -1 when there is no authority or no port
urlPath(u)stringthe path
urlQuery(u)stringthe query string
urlFragment(u)stringthe fragment

Escaping for markup and shells

std/text/escape escapes text for the context it will be placed in. Each function produces text that is safe in exactly that context and no other:

FunctionContext
htmlEscape(s)element text in HTML
htmlAttrEscape(s)a quoted HTML attribute value
htmlUnescape(s)reverses HTML escapes
shellQuotePosix(s)one argument for a POSIX shell
shellQuoteWindows(s)one argument for a Windows command line
sqlEscapeLiteral(s)a string literal inside an SQL statement

Attention Escaping protects one context. Do not reuse an HTML escape inside a shell command, or a shell quote inside SQL. Use the function for the place the text lands. sqlEscapeLiteral escapes a literal only: prepared statements remain the way to pass values to a database.

Hashing

use std::text::hashing;

let h : i64 = hashing::hashString("hello");      // keyed 64-bit hash, same key every run
let c : i64 = hashing::hashCombine(h, hashing::hashI64(42));
FunctionEffect
hashString(s)64-bit hash of a string, with a fixed key; deterministic across runs
hashStringSeeded(s, k0, k1)the same mixer with a caller-chosen key
hashI64(v)a SplitMix64 finalizer over an integer
hashCombine(a, b)fold a second hash into the first
fnv1aBytes(s)64-bit FNV-1a over the bytes
djb2Bytes(s)djb2 over the bytes

These are fast non-cryptographic hashes. The string hashes are what HashMap<string, V> builds on, and the container uses a random per-process seed, so an attacker cannot precompute collisions against it. Code that builds its own table on hashString must supply its own seed through hashStringSeeded.

Checksums

use std::text::checksum;

let sum : i64 = checksum::crc32("hello");        // 907060870
let adl : i64 = checksum::adler32("hello");

crc32 and adler32 return the checksum of a string. crc32Update(seed, data) and adler32Update(seed, data) fold more bytes into a running value. Pass the previous result as seed to checksum a stream in chunks. Neither checksum is a cryptographic hash.

UUIDs

std/text/uuid generates and validates version-4 UUIDs:

use std::text::uuid;

fn main() : i32 ! ParseException {
    let id : string = uuid::uuidV4();            // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    let hex : string = uuid::uuidV4Hex();        // same, 32 hex characters, no dashes

    if (uuid::uuidIsValid(id)) {
        println("ok");
    }

    let canon : string = uuid::uuidNormalize("F47AC10B-58CC-4372-A567-0E02B2C3D479");
    // "f47ac10b58cc4372a5670e02b2c3d479": dashes stripped, lowercased.
    // Throws ParseException on a value that is not a UUID.
    return 0;
}
FunctionReturnsEffect
uuidV4()stringa fresh UUID in the canonical 36-character dashed form
uuidV4Hex()stringa fresh UUID as 32 hex characters, no dashes
uuidIsValid(s)booltrue when s is a well-formed UUID, dashed or not; never throws
uuidNormalize(s)stringthe 32 hex digits, lowercased; throws ParseException

Attention UUIDs here are drawn from a SplitMix64 generator private to the uuid module, seeded from the wall and monotonic clocks. It is independent of Random, and Random::seed does not affect it. They are unique enough for a log line or a cache key. They are not suitable for security tokens, session secrets or anything an attacker must not guess.

Semantic versions

std/text/version parses and compares semver strings. It answers “is this release newer” correctly, so 1.10.0 sorts after 1.2.0, where a plain string comparison would get it wrong:

use std::text::version;

fn main() : i32 ! ParseException {
    let cmp : i32 = version::versionCompare("1.2.0", "1.10.0");   // -1: older
    if (version::versionIsValid("2.0.1-rc.1")) {
        println("valid");
    }

    let major : i32 = version::versionMajor("2.0.1");              // 2
    let pre : string = version::versionPrerelease("2.0.1-rc.1");   // "rc.1"
    return cmp;
}
FunctionReturnsEffect
versionCompare(a, b)i32-1, 0 or 1, in semver precedence; throws ParseException on a bad version
versionIsValid(v)booltrue when v parses as semver; never throws
versionMajor(v) / versionMinor(v) / versionPatch(v)i32the numeric component; throws ParseException
versionPrerelease(v)stringthe text after -, or ""; throws ParseException
versionBuild(v)stringthe text after +, or ""; throws ParseException

versionCompare orders by major, minor and patch, and then by prerelease. A prerelease sorts before its release, so a release always outranks its own prereleases.

Limits / Uncabled

FeatureStateDetail or workaround
Multi-line CSV records (a quote straddling a newline)Not supportedSplit on "\n" first and parse each line
Regex backreferences and lookaroundNot supported (Rust regex syntax)Use two passes, or a small hand-written scanner
Nested JSON membersJson reads top-level keys onlyParse the document into your own structure, or flatten it before the lookup
Building a JSON treeNot provided: Json is a cursor, not a document modelBuild the text with StringBuilder and the json* helpers
First-only replaceNot provided: replace rewrites every occurrenceindexOf and substring
Cryptographic UUIDs and hashesNot provided by uuid, hashing or checksumUse a platform CSPRNG or hash through the C interop layer

Patterns

Joining

use std::collections::ArrayList;
use std::text::StringBuilder;

fn join(parts : ArrayList<string>, sep : string) : string {
    let sb : StringBuilder = new StringBuilder();
    let mut i : i32 = 0;
    while (i < parts.size()) {
        if (i > 0) {
            sb.append(sep);
        }
        sb.append(parts.get(i) ?? "");      // in range: never null
        i = i + 1;
    }
    return sb.toString();
}

Formatting numbers with padding

fn formatI32Padded(v : i32, width : i32) : string {
    return v.toString().padStart(width, 48);     // 48 = '0'
}

Common pitfalls

== on a class

class Point {
    x : i32;
    y : i32;
    constructor(x : i32, y : i32) {
        self.x = x;
        self.y = y;
    }
}

let p : Point = new Point(1, 2);
let q : Point = new Point(1, 2);
if (p == q) { /* false: same fields, different objects */ }

== compares a reference against a reference, so two Points with identical fields are still different objects. Give the class an equals: @derive(Eq) writes one that compares the fields, or declare it by hand. A string is the exception. == on two strings compares their contents, because content is the only identity a string has.

.length counts characters, not bytes

let s : string = "café";
let n : i32 = s.length;                          // 4: é is one character

.length is the codepoint count: café is 4 characters even though é occupies two bytes in UTF-8. Walk characters with charAt (it returns -1 once you pass the end) when you need per-character access. Reach a raw byte with .byteAt(i), bounded by .byteLength (5 here, not 4).

Iterative + in a loop

use std::text::StringBuilder;

fn slowJoin() : string {
    // BAD: quadratic, every pass copies the growing string.
    let mut s : string = "";
    for (i of 0..1000) { s = s + " " + i; }
    return s;
}

fn fastJoin() : string {
    // GOOD: linear, one buffer, one final copy.
    let sb : StringBuilder = new StringBuilder();
    for (i of 0..1000) { sb.append(" ").appendI32(i); }
    return sb.toString();
}

See also

stringstextutf-8formatting