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.
Search
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();
} | Method | Returns | Effect |
|---|---|---|
append(s) | StringBuilder | append a string |
appendChar(c) | StringBuilder | append a codepoint (i32) |
appendI32(v) / appendI64(v) | StringBuilder | append an integer |
appendF64(v) | StringBuilder | append a float |
appendBool(v) | StringBuilder | append "true" or "false" |
length() | i32 | character count |
byteLength() | i64 | byte count |
isEmpty() | bool | true when nothing has been appended |
toString() | string | a fresh owned copy of the contents; the builder stays usable |
clear() | StringBuilder | empty the buffer for reuse |
reverse() | StringBuilder | reverse 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);
} | Function | Returns | Effect |
|---|---|---|
jsonValidate(text) | bool | true when text is a complete JSON document; throws ParseException when it nests deeper than MAX_JSON_NESTING_DEPTH |
jsonQuoteString(s) | string | s escaped and wrapped in double quotes |
jsonEscapeString(s) | string | s escaped, without outer quotes |
jsonI64ToString(v) | string | integer as JSON text |
jsonF64ToString(v) | string | float as JSON text; NaN and infinities become null |
jsonBoolToString(b) | string | true or false |
jsonNull() | string | the 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 member | Returns | When the key is absent |
|---|---|---|
Json::parse(text) | Json | throws ParseException when text is not valid JSON |
has(key) | bool | false |
text(key) | string | "" |
int(key) | i64 | 0 |
num(key) | f64 | 0.0 |
flag(key) | bool | false |
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.
| Function | Returns | Effect |
|---|---|---|
csvFieldCount(row) | i32 | number of fields in one row, quoting-aware |
csvField(row, i) | string | the i-th field, unquoted; throws IndexOutOfBoundsException |
csvEncode(field) | string | quoted when it contains ,, " or a newline |
csvJoin2(a, b) | string | two 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
| Method | Returns | Effect |
|---|---|---|
matches(s) | bool | whole-string test, anchored at both ends |
find(s) | bool | true when the pattern occurs anywhere in s |
replaceAll(s, repl) | string | rewrite every match |
replaceFirst(s, repl) | string | rewrite the first match |
split(s) | string | the pieces of s between matches, joined by \n |
matcher(s) | Matcher | a cursor over the matches of s |
pattern() | string | the source the pattern was compiled from |
close() | void | releases 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 method | Returns | Effect |
|---|---|---|
find() | bool | advance to the next match; false when none is left |
matches() | bool | whole-input test for the current input |
group() | string | the whole current match |
groupAt(i) | string | capture group i; group 0 is the whole match |
groupCount() | i32 | the number of capture groups |
start() / end() | i32 | offsets of the current match |
reset() | void | start scanning from the beginning again |
replaceAll(repl) | string | rewrite 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;
} | Function | Returns | Notes |
|---|---|---|
base64Encode(s) / base64UrlEncode(s) | string | never fails |
base64Decode(s) / base64UrlDecode(s) | string | throws ParseException on a bad symbol or invalid UTF-8, IllegalArgumentException on a decoded NUL |
hexEncode(s) | string | two hex digits per byte, never fails |
hexDecode(s) | string | throws 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;
} | Function | Returns | Effect |
|---|---|---|
urlEncode(s) / urlDecode(s) | string | percent-encoding; urlDecode throws ParseException |
urlEncodeForm(s) / urlDecodeForm(s) | string | the form-encoding variant of the same pair (HTML form rules) |
urlScheme(u) | string | the scheme, such as https |
urlHost(u) | string | the host name |
urlPort(u) | i32 | the port number given in the URL, or -1 when there is no authority or no port |
urlPath(u) | string | the path |
urlQuery(u) | string | the query string |
urlFragment(u) | string | the 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:
| Function | Context |
|---|---|
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.
sqlEscapeLiteralescapes 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)); | Function | Effect |
|---|---|
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;
} | Function | Returns | Effect |
|---|---|---|
uuidV4() | string | a fresh UUID in the canonical 36-character dashed form |
uuidV4Hex() | string | a fresh UUID as 32 hex characters, no dashes |
uuidIsValid(s) | bool | true when s is a well-formed UUID, dashed or not; never throws |
uuidNormalize(s) | string | the 32 hex digits, lowercased; throws ParseException |
Attention UUIDs here are drawn from a SplitMix64 generator private to the
uuidmodule, seeded from the wall and monotonic clocks. It is independent ofRandom, andRandom::seeddoes 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;
} | Function | Returns | Effect |
|---|---|---|
versionCompare(a, b) | i32 | -1, 0 or 1, in semver precedence; throws ParseException on a bad version |
versionIsValid(v) | bool | true when v parses as semver; never throws |
versionMajor(v) / versionMinor(v) / versionPatch(v) | i32 | the numeric component; throws ParseException |
versionPrerelease(v) | string | the text after -, or ""; throws ParseException |
versionBuild(v) | string | the 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
| Feature | State | Detail or workaround |
|---|---|---|
| Multi-line CSV records (a quote straddling a newline) | Not supported | Split on "\n" first and parse each line |
| Regex backreferences and lookaround | Not supported (Rust regex syntax) | Use two passes, or a small hand-written scanner |
| Nested JSON members | Json reads top-level keys only | Parse the document into your own structure, or flatten it before the lookup |
| Building a JSON tree | Not provided: Json is a cursor, not a document model | Build the text with StringBuilder and the json* helpers |
First-only replace | Not provided: replace rewrites every occurrence | indexOf and substring |
| Cryptographic UUIDs and hashes | Not provided by uuid, hashing or checksum | Use 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
std/textreference: full string surfacestd/text/jsonreference: JSON helpers and the cursorstd/text/regexreference: regex API- Collections → HashMap word counter: practical string keys
- Concept index: every string and text concept cross-linked