std/text
std/text — string operations and parsing.
Free functions over the primitive string type, backing thestring members (the .length property, .equals(), .byteAt(), …)
the compiler lowers onto them.
The byte-level operations (search, comparison, slicing by character
index, formatting, the polynomial hash) are pure Axle, built on thebyteAt primitive (strByteAt) and a strByteLen O(1) header read —
both @link(symbol = …) bindings straight to the runtime, which owns the
string layout. What stays native (a Rust #[axle_native] shim) is
what cannot be reproduced byte-for-byte without it:stringFromBytes / __string_concat (the raw bridges),
Unicode whitespace (isBlank / trim*) and case folding
(toLowerCase / toUpperCase), and IEEE-754 float parse / format
(parseF64 / __f64ToString); the integer / bool parsers trim
Unicode whitespace before parsing, so they stay native too.
Free functions
| Type | Method and description |
|---|---|
| stringFromBytes(buf : ptr, len : i64) : string Copy len bytes from a raw libc buffer into an owned string(UTF-8, lossy). The read-side counterpart to passing a stringstraight to a char* libc binding. The result owns its allocation,so the source buffer may be freed immediately after. An interior NUL is refused: the payload is NUL-terminated for the C boundary, and a byte inside would cut that view short. The raise is part of the declaration so the call site gets a post-call poll — a native's !clause is its whole fallibility contract. |
| stringFromBytesRaw(buf : ptr, len : i64) : string The total byte bridge: copy len bytes from a raw buffer into an ownedstring, every byte preserved, an interior NUL included. Invalid UTF-8 isreplaced with U+FFFD, as in [ stringFromBytes].For builders whose bytes are already in hand (a digit run, a hex alphabet, a substring of an Axle string) and therefore can never contain a NUL. Those sites must not be charged the strict bridge's exception: the raise cannot fire there, and declaring it on them would make the whole string surface checked-throwing. |
| bytesToString(buf : i8[], len : i64) : string Build an owned string from the first len bytes of a byte array.The array → ptr decay required by the native bridge is confinedto this function's unsafe block.The bytes are copied verbatim, an interior NUL included. A builder reaches this with bytes it derived from an Axle string or an ASCII alphabet, so a NUL cannot appear; the strict, validating door is [ bytesToStringStrict]. |
| bytesToStringStrict(buf : i8[], len : i64) : string The validating twin of [bytesToString]: build an owned string from thefirst len bytes of a byte array, refusing an interior NUL.For a decoder whose output is arbitrary bytes (hex, base64, a child's captured stream): the NUL check is the difference, and it is declared, so a caller gets the post-call poll. |
| bufferPtr(buf : i8[]) : ptr<i8> Decay a byte array to the typed pointer the scratch-buffer routines ( std::core::bytes) index. The array → ptr decay is confined here.The result stays a pointer the whole way down: an i64 address wouldforce each access to rebuild a pointer with inttoptr, which coststwo extra instructions and, because the result has no provenance, stops alias analysis from proving anything about the buffer. |
| bufferAddr(buf : i8[]) : i64 The same base address as an i64, for the few sites that hand itstraight to a libc binding taking an opaque ptr (fread / fwrite/ realpath) rather than indexing it.Prefer bufferPtr for anything that reads or writes bytes: theinteger form loses provenance, and every access through it has to rebuild a pointer. This exists only so the decay itself is still written once. |
| spanFits(buf : i8[], offset : i64, len : i64) : bool Does the window buf[offset .. offset+len) lie inside buf?The one place a caller-supplied (offset, len) is measured against thebuffer it addresses. Every site that reaches a byte through [ bufferAddr] has already left the array behind — the FFI call it handsthe address to sees a bare pointer and a count, and no bound at all. So the measurement has to happen here, while buf is still an array andstill knows its own length. It refuses rather than clamping. A short read is a legitimate answer from a stream; a request reaching past the buffer is a caller that has miscounted, and silently serving a prefix of it hides the miscount until the data is wrong somewhere else. The addition is written as a subtraction because Axle's + wraps: offset + len on two large valuesis a small number that passes. |
| addrAsPtr(addr : i64) : ptr Reinterpret a buffer address as the opaque ptr an FFI binding takes —the read side of bufferAddr, for a call that needs an offset into abuffer rather than its base. Here, and only here, so the i64 -> ptr decay has one site the waybufferPtr gives the array -> ptr one its site. Prefer bufferPtrwhenever the result is indexed: an address that has been through an integer carries no provenance, and every access through it has to rebuild a pointer. |
| __stringByteAt(s : string, i : i64) : i32 Raw byte 0..255 at byte-index i, or -1 if out of range. Theprimitive every hand-rolled scanner builds on; backed directly by the runtime's bounds-checked accessor ( strByteAt) since the runtime ownsthe string layout. |
| __string_concat(a : string, b : string) : string Runtime helper backing a + b when either operand is a string. Theresult is a fresh owned string; the operands are left untouched. |
| __stringRepeat(s : string, n : i32) : string s repeated n times ("" when n <= 0). Builds the result in asingle allocation filled in place — no scratch buffer, no re-copy. |
| __stringConcat(a : string, b : string) : string Backs the .concat(other) method — distinct from the + operator, whichlowers to the native __string_concat. Joins a and b into a freshowned string ("" when both are empty). |
| __stringIsBlank(s : string) : bool True when s is empty or contains only Unicode whitespace. |
| __stringTrim(s : string) : string Drop leading and trailing Unicode whitespace, returning an owned string. |
| __stringTrimStart(s : string) : string Drop leading Unicode whitespace, returning an owned string. |
| __stringTrimEnd(s : string) : string Drop trailing Unicode whitespace, returning an owned string. |
| __stringToLowerCase(s : string) : string Full Unicode lowercase folding (locale-independent), as an owned string. |
| __stringToUpperCase(s : string) : string Full Unicode uppercase folding (locale-independent), as an owned string. |
| parseI32(s : string) : i32 Parse a base-10 i32, trimming surrounding Unicode whitespace first. |
| parseI64(s : string) : i64 Parse a base-10 i64, trimming surrounding Unicode whitespace first. |
| parseU32(s : string) : u32 Parse a base-10 u32, trimming surrounding Unicode whitespace first.A leading - is refused, -0 included. |
| parseU64(s : string) : u64 Parse a base-10 u64, trimming surrounding Unicode whitespace first.A leading - is refused, -0 included. |
| parseF64(s : string) : f64 Parse an IEEE-754 f64, trimming surrounding Unicode whitespace first.The grammar is the one a source literal has: inf, infinity, NaN andan exponent too large for f64 are refused rather than answered as thenon-finite value they would produce. |
| parseBool(s : string) : bool Parse "true" / "false" (after trimming Unicode whitespace), in any ASCIIcase. "1", "0", "yes" and "no" are not boolean literals in thislanguage's source and are refused here too. |
| __stringToI32(s : string) : i32 s.toI32() — @throws ParseException when the text is not a 32-bit integer. |
| __stringToI64(s : string) : i64 s.toI64() — @throws ParseException when the text is not a 64-bit integer. |
| __stringToF64(s : string) : f64 s.toF64() — @throws ParseException when the text is not a float literal. |
| __stringToBool(s : string) : bool s.toBool() — @throws ParseException for anything but "true" / "false". |
| __f64ToString(v : f64) : string IEEE-754 shortest round-trip text of v (the value parseF64 inverts). |
| __txtSubstr(s : string, start : i64, end : i64) : string Copy bytes [start, end) of s into an owned string. |
| __charCountPrefix(s : string, byteEnd : i64) : i32 Count of UTF-8 characters in [0, byteEnd) — every byte that is nota continuation byte ( 0b10xxxxxx) starts a new character. Backed bythe runtime's O(1) header read + one pass over the byte slice ( strCharCountPrefix), not a per-byte byteAt FFI loop (which madelength / indexOf / substring O(n) function calls on the length). |
| __charByteIndex(s : string, srcLen : i64, charIdx : i32) : i64 Byte offset of the charIdx-th character in s (whose byte lengthis srcLen): the string end when charIdx equals the charactercount, or -1 when it exceeds it. |
| __charWidth(lead : i32) : i64 UTF-8 width (1..4 bytes) of the character whose lead byte is lead.A stray continuation byte counts as width 1 to keep scans advancing. |
| __decodeCodepoint(s : string, byteOffset : i64) : i32 Decode the Unicode codepoint of the character starting atbyteOffset (assumed valid UTF-8). |
| __txtPutUtf8(buffer : ptr<i8>, offset : i64, codepoint : i32) : i64 UTF-8 encode codepoint (invalid scalars folded to U+FFFD, matchingchar::from_u32(..).unwrap_or(..)) into buffer at offset,returning the offset past the bytes written. |
| __byteIndexOf(s : string, sourceLen : i64, sub : string, subLen : i64, from : i64) : i64 Byte offset of the first occurrence of sub in s at or afterfrom, or -1. An empty needle matches at from (mirrorsstr::find("")). |
| __txtFormatDecimal(v : i64) : string Decimal text of a signed 64-bit value. Builds the result in a single right-sized allocation, digits formatted in place (handles the minimum value without negating). |
| __stringLength(s : string) : i32 Number of UTF-8 characters in s. |
| __stringIsEmpty(s : string) : bool True when s holds no bytes. |
| __stringSubstring(s : string, start : i32, end : i32) : string Substring of the characters [start, end). RaisesIndexOutOfBoundsException when the range is negative, inverted, orpast the character count. |
| __stringSubstringFrom(s : string, start : i32) : string Substring from character start to the end. RaisesIndexOutOfBoundsException when start is negative or past thecharacter count. |
| __stringStartsWith(s : string, prefix : string) : bool True when s begins with prefix (byte comparison; empty prefix is always true). |
| __stringEndsWith(s : string, suffix : string) : bool True when s ends with suffix (byte comparison; empty suffix is always true). |
| __stringContains(s : string, sub : string) : bool True when sub occurs anywhere in s (empty sub always matches). |
| __stringIndexOf(s : string, sub : string) : i32 Character index of the first occurrence of sub, or -1. |
| __stringLastIndexOf(s : string, sub : string) : i32 Character index of the last occurrence of sub, or -1. |
| __stringReplace(s : string, from : string, to : string) : string Replace every non-overlapping occurrence of from with to. Anempty from inserts to around every character (mirroringstr::replace). |
| __stringReverse(s : string) : string Reverse by character (not by byte) so multi-byte UTF-8 stays valid. |
| __stringCharAt(s : string, i : i32) : i32 Unicode codepoint at character index i, or -1 if out of range. |
| __stringPadStart(s : string, len : i32, c : i32) : string Pad s on the left with character c until it spans lencharacters (no-op when already at least that long). |
| __stringPadEnd(s : string, len : i32, c : i32) : string Pad s on the right with character c until it spans lencharacters (no-op when already at least that long). |
| __stringHashCode(s : string) : i32 31-polynomial hash over the codepoints: h = 31*h + c, wrapping ini32 (the truncation each step matches the native wrapping_*).Reads length through the __string_byte_len compiler builtin like thecomparison family below it (see the note above __stringEquals), notthe strByteLen FFI shim. |
| __stringEquals(a : string, b : string) : bool Byte-exact equality (no case folding, no Unicode normalisation). Every == between two strings lands here, so it is the hottest loop astring-keyed table has. Once the lengths are known equal the comparison is a memory compare of a known extent, and it is done eight bytes at a time: one i64 load per side per word instead of one byte load per side per byte.The tail is a single overlapping word — re-reading bytes already found equal costs nothing and removes the loop. It does not delegate to bytesMatchAt, which is shared with indexOf /startsWith / endsWith / replace and must keep answering for an arbitraryoffset and a needle shorter than its haystack. |
| __stringEqualsIgnoreCase(a : string, b : string) : bool ASCII case-insensitive equality (only A-Z ↔ a-z are folded,matching eq_ignore_ascii_case). |
| __stringCompare(a : string, b : string) : i32 Lexicographic byte comparison: <0, 0, >0. A proper prefix sorts before the longer string. |
| __i32ToString(v : i32) : string Decimal text of a signed 32-bit value. |
| __i64ToString(v : i64) : string Decimal text of a signed 64-bit value. |
| __boolToString(v : bool) : string "true" or "false". |
| i64ToString(v : i64) : string Decimal text of a signed 64-bit value — the public entry point onto the module's shared decimal formatter, so a caller outside this module reuses one implementation instead of recreating it. n.toString() isthe spelling most code reaches for; this is the same formatter under a name a module can use. |
| f64ToString(v : f64) : string IEEE-754 round-trip text of v — the public entry point onto thenative __f64ToString shortest-round-trip formatter, so a calleroutside this module can format a float without touching the reserved __-prefixed primitive, which E0002 forbids it to name. |
| __f32ToString(v : f32) : string v.toString() on an out-of-range f32 — the primitive-method entry forf32, rendering through the f64 formatter. Every f32 widens to f64exactly, so the shortest f64 round-trip text is the shortest f32 one. |
| __u8ToString(v : u8) : string v.toString() on the unsigned widths that fit an i64. u8 / u16 /u32 all widen into i64 without loss, so the signed decimal formatterrenders them exactly. |
| __u16ToString(v : u16) : string v.toString() — @param v u16 to render in base 10. |
| __u32ToString(v : u32) : string v.toString() — @param v u32 to render in base 10. |
| __u64ToString(v : u64) : string v.toString() on a u64 — the widths above i64::MAX have no signedrendering, so this formats unsigned end to end. The digits are produced least-significant first by repeated division and written into a heap buffer right to left, so the buffer already reads most-significant first when [ bytesToString] copies it out. |
Method detail
#stringFromBytes
Copy len bytes from a raw libc buffer into an owned string
(UTF-8, lossy). The read-side counterpart to passing a string
straight to a char* libc binding. The result owns its allocation,
so the source buffer may be freed immediately after.
An interior NUL is refused: the payload is NUL-terminated for the C
boundary, and a byte inside would cut that view short. The raise is part of
the declaration so the call site gets a post-call poll — a native's !
clause is its whole fallibility contract.
buf raw source buffer to copy fromlen number of bytes to copy out of bufIllegalArgumentException when the bytes hold an interior NUL.#stringFromBytesRaw
The total byte bridge: copy len bytes from a raw buffer into an ownedstring, every byte preserved, an interior NUL included. Invalid UTF-8 is
replaced with U+FFFD, as in [stringFromBytes].
For builders whose bytes are already in hand (a digit run, a hex alphabet, a
substring of an Axle string) and therefore can never contain a NUL. Those
sites must not be charged the strict bridge's exception: the raise cannot
fire there, and declaring it on them would make the whole string surface
checked-throwing.
buf raw source buffer to copy fromlen number of bytes to copy out of buf#bytesToString
Build an owned string from the first len bytes of a byte array.
The array → ptr decay required by the native bridge is confined
to this function's unsafe block.
The bytes are copied verbatim, an interior NUL included. A builder reaches
this with bytes it derived from an Axle string or an ASCII alphabet, so a
NUL cannot appear; the strict, validating door is [bytesToStringStrict].
buf byte array whose contents are copiedlen number of bytes to read from buf#bytesToStringStrict
The validating twin of [bytesToString]: build an owned string from the
first len bytes of a byte array, refusing an interior NUL.
For a decoder whose output is arbitrary bytes (hex, base64, a child's
captured stream): the NUL check is the difference, and it is declared, so a
caller gets the post-call poll.
buf byte array whose contents are copiedlen number of bytes to read from bufIllegalArgumentException when the bytes hold an interior NUL.#bufferPtr
Decay a byte array to the typed pointer the scratch-buffer routines
(std::core::bytes) index. The array → ptr decay is confined here.
The result stays a pointer the whole way down: an i64 address would
force each access to rebuild a pointer with inttoptr, which costs
two extra instructions and, because the result has no provenance,
stops alias analysis from proving anything about the buffer.
buf byte array whose base address is taken#bufferAddr
The same base address as an i64, for the few sites that hand it
straight to a libc binding taking an opaque ptr (fread / fwrite
/ realpath) rather than indexing it.
Prefer bufferPtr for anything that reads or writes bytes: the
integer form loses provenance, and every access through it has to
rebuild a pointer. This exists only so the decay itself is still
written once.
buf byte array whose base address is taken#spanFits
Does the window buf[offset .. offset+len) lie inside buf?
The one place a caller-supplied (offset, len) is measured against the
buffer it addresses. Every site that reaches a byte through
[bufferAddr] has already left the array behind — the FFI call it hands
the address to sees a bare pointer and a count, and no bound at all. So
the measurement has to happen here, while buf is still an array and
still knows its own length.
It refuses rather than clamping. A short read is a legitimate answer
from a stream; a request reaching past the buffer is a caller that has
miscounted, and silently serving a prefix of it hides the miscount until
the data is wrong somewhere else. The addition is written as a
subtraction because Axle's + wraps: offset + len on two large values
is a small number that passes.
buf the array the window is taken fromoffset first index of the windowlen window length in bytes#addrAsPtr
Reinterpret a buffer address as the opaque ptr an FFI binding takes —
the read side of bufferAddr, for a call that needs an offset into a
buffer rather than its base.
Here, and only here, so the i64 -> ptr decay has one site the waybufferPtr gives the array -> ptr one its site. Prefer bufferPtr
whenever the result is indexed: an address that has been through an
integer carries no provenance, and every access through it has to
rebuild a pointer.
addr base address, from bufferAddr, plus any byte offset#__stringByteAt
Raw byte 0..255 at byte-index i, or -1 if out of range. The
primitive every hand-rolled scanner builds on; backed directly by the
runtime's bounds-checked accessor (strByteAt) since the runtime owns
the string layout.
s string to readi byte offset into s, 0-based#__string_concat
Runtime helper backing a + b when either operand is a string. The
result is a fresh owned string; the operands are left untouched.
a left operand, placed first in the resultb right operand, appended after a#__stringRepeat
s repeated n times ("" when n <= 0). Builds the result in a
single allocation filled in place — no scratch buffer, no re-copy.
s string to repeatn number of repetitions#__stringConcat
Backs the .concat(other) method — distinct from the + operator, which
lowers to the native __string_concat. Joins a and b into a fresh
owned string ("" when both are empty).
a left operand, placed first in the resultb right operand, appended after a#__stringIsBlank
True when s is empty or contains only Unicode whitespace.
s string to test for blankness#__stringTrim
Drop leading and trailing Unicode whitespace, returning an owned string.
s string to trim on both ends#__stringTrimStart
Drop leading Unicode whitespace, returning an owned string.
s string to trim on the leading end#__stringTrimEnd
Drop trailing Unicode whitespace, returning an owned string.
s string to trim on the trailing end#__stringToLowerCase
Full Unicode lowercase folding (locale-independent), as an owned string.
s string to lowercase#__stringToUpperCase
Full Unicode uppercase folding (locale-independent), as an owned string.
s string to uppercase#parseI32
Parse a base-10 i32, trimming surrounding Unicode whitespace first.
s decimal text to parseParseException when the text is empty or not a valid 32-bit integer.#parseI64
Parse a base-10 i64, trimming surrounding Unicode whitespace first.
s decimal text to parseParseException when the text is empty or not a valid 64-bit integer.#parseU32
Parse a base-10 u32, trimming surrounding Unicode whitespace first.
A leading - is refused, -0 included.
s decimal text to parseParseException when the text is empty, negative or not a valid 32-bit unsigned integer.#parseU64
Parse a base-10 u64, trimming surrounding Unicode whitespace first.
A leading - is refused, -0 included.
s decimal text to parseParseException when the text is empty, negative or not a valid 64-bit unsigned integer.#parseF64
Parse an IEEE-754 f64, trimming surrounding Unicode whitespace first.
The grammar is the one a source literal has: inf, infinity, NaN and
an exponent too large for f64 are refused rather than answered as the
non-finite value they would produce.
s floating-point text to parseParseException when the text is not a finite float literal.#parseBool
Parse "true" / "false" (after trimming Unicode whitespace), in any ASCII
case. "1", "0", "yes" and "no" are not boolean literals in this
language's source and are refused here too.
s bool text to parseParseException for any other text.#__stringToI32
s.toI32() — @throws ParseException when the text is not a 32-bit integer.
#__stringToI64
s.toI64() — @throws ParseException when the text is not a 64-bit integer.
#__stringToF64
s.toF64() — @throws ParseException when the text is not a float literal.
#__stringToBool
s.toBool() — @throws ParseException for anything but "true" / "false".
#__f64ToString
IEEE-754 shortest round-trip text of v (the value parseF64 inverts).
v f64 to render#__txtSubstr
Copy bytes [start, end) of s into an owned string.
s source stringstart inclusive start byte offset into s, 0-basedend exclusive end byte offset into s#__charCountPrefix
Count of UTF-8 characters in [0, byteEnd) — every byte that is not
a continuation byte (0b10xxxxxx) starts a new character. Backed by
the runtime's O(1) header read + one pass over the byte slice
(strCharCountPrefix), not a per-byte byteAt FFI loop (which madelength / indexOf / substring O(n) function calls on the length).
s source stringbyteEnd exclusive end byte offset of the prefix to count#__charByteIndex
Byte offset of the charIdx-th character in s (whose byte length
is srcLen): the string end when charIdx equals the character
count, or -1 when it exceeds it.
s source stringsrcLen byte length of scharIdx character index to locate, 0-based#__charWidth
UTF-8 width (1..4 bytes) of the character whose lead byte is lead.
A stray continuation byte counts as width 1 to keep scans advancing.
lead lead byte of a UTF-8 sequence#__decodeCodepoint
Decode the Unicode codepoint of the character starting atbyteOffset (assumed valid UTF-8).
s source stringbyteOffset byte offset of the character's lead byte#__txtPutUtf8
UTF-8 encode codepoint (invalid scalars folded to U+FFFD, matchingchar::from_u32(..).unwrap_or(..)) into buffer at offset,
returning the offset past the bytes written.
buffer destination buffer base addressoffset byte offset at which to write the encoded bytescodepoint Unicode scalar to encode#__byteIndexOf
Byte offset of the first occurrence of sub in s at or afterfrom, or -1. An empty needle matches at from (mirrorsstr::find("")).
s haystack stringsourceLen byte length of ssub needle substring to search forsubLen byte length of subfrom byte offset at which the search starts#__txtFormatDecimal
Decimal text of a signed 64-bit value. Builds the result in a single
right-sized allocation, digits formatted in place (handles the minimum
value without negating).
v signed integer to render in base 10#__stringLength
Number of UTF-8 characters in s.
s string to measure#__stringIsEmpty
True when s holds no bytes.
s string to test for emptiness#__stringSubstring
Substring of the characters [start, end). RaisesIndexOutOfBoundsException when the range is negative, inverted, or
past the character count.
s source stringstart inclusive start character index, 0-basedend exclusive end character index#__stringSubstringFrom
Substring from character start to the end. RaisesIndexOutOfBoundsException when start is negative or past the
character count.
s source stringstart inclusive start character index, 0-based#__stringStartsWith
True when s begins with prefix (byte comparison; empty prefix is always true).
s string to testprefix candidate leading substring#__stringEndsWith
True when s ends with suffix (byte comparison; empty suffix is always true).
s string to testsuffix candidate trailing substring#__stringContains
True when sub occurs anywhere in s (empty sub always matches).
s haystack stringsub needle substring to search for#__stringIndexOf
Character index of the first occurrence of sub, or -1.
s haystack stringsub needle substring to search for#__stringLastIndexOf
Character index of the last occurrence of sub, or -1.
s haystack stringsub needle substring to search for#__stringReplace
Replace every non-overlapping occurrence of from with to. An
empty from inserts to around every character (mirroringstr::replace).
s source stringfrom substring to search for and replaceto replacement substring#__stringReverse
Reverse by character (not by byte) so multi-byte UTF-8 stays valid.
s string to reverse#__stringCharAt
Unicode codepoint at character index i, or -1 if out of range.
s source stringi character index, 0-based#__stringPadStart
Pad s on the left with character c until it spans len
characters (no-op when already at least that long).
s string to padlen target length in charactersc Unicode codepoint of the pad character#__stringPadEnd
Pad s on the right with character c until it spans len
characters (no-op when already at least that long).
s string to padlen target length in charactersc Unicode codepoint of the pad character#__stringHashCode
31-polynomial hash over the codepoints: h = 31*h + c, wrapping ini32 (the truncation each step matches the native wrapping_*).
Reads length through the __string_byte_len compiler builtin like the
comparison family below it (see the note above __stringEquals), not
the strByteLen FFI shim.
s string to hash#__stringEquals
Byte-exact equality (no case folding, no Unicode normalisation).
Every == between two strings lands here, so it is the hottest loop a
string-keyed table has. Once the lengths are known equal the comparison is a
memory compare of a known extent, and it is done eight bytes at a time:
one i64 load per side per word instead of one byte load per side per byte.
The tail is a single overlapping word — re-reading bytes already found equal
costs nothing and removes the loop.
It does not delegate to bytesMatchAt, which is shared with indexOf /startsWith / endsWith / replace and must keep answering for an arbitrary
offset and a needle shorter than its haystack.
a first string to compareb second string to compare#__stringEqualsIgnoreCase
ASCII case-insensitive equality (only A-Z ↔ a-z are folded,
matching eq_ignore_ascii_case).
a first string to compareb second string to compare#__stringCompare
Lexicographic byte comparison: <0, 0, >0. A proper prefix sorts
before the longer string.
a left operand of the comparisonb right operand of the comparison#__i32ToString
Decimal text of a signed 32-bit value.
v i32 to render in base 10#__i64ToString
Decimal text of a signed 64-bit value.
v i64 to render in base 10#__boolToString
"true" or "false".
v bool to render#i64ToString
Decimal text of a signed 64-bit value — the public entry point onto
the module's shared decimal formatter, so a caller outside this module
reuses one implementation instead of recreating it. n.toString() is
the spelling most code reaches for; this is the same formatter under a
name a module can use.
v i64 to render in base 10#f64ToString
IEEE-754 round-trip text of v — the public entry point onto the
native __f64ToString shortest-round-trip formatter, so a caller
outside this module can format a float without touching the reserved__-prefixed primitive, which E0002 forbids it to name.
v f64 to render#__f32ToString
v.toString() on an out-of-range f32 — the primitive-method entry forf32, rendering through the f64 formatter. Every f32 widens to f64
exactly, so the shortest f64 round-trip text is the shortest f32 one.
v f32 to render#__u8ToString
v.toString() on the unsigned widths that fit an i64. u8 / u16 /u32 all widen into i64 without loss, so the signed decimal formatter
renders them exactly.
v u8 to render in base 10#__u16ToString
v.toString() — @param v u16 to render in base 10.
#__u32ToString
v.toString() — @param v u32 to render in base 10.
#__u64ToString
v.toString() on a u64 — the widths above i64::MAX have no signed
rendering, so this formats unsigned end to end. The digits are produced
least-significant first by repeated division and written into a heap buffer
right to left, so the buffer already reads most-significant first when
[bytesToString] copies it out.
v u64 to render in base 10C class StringBuilder
Growable UTF-8 byte buffer. data is an owned i8[] — the compiler
frees it through the synthesised destructor at scope exit, so no
manual release is needed. Mutating methods return self so chains
stay idiomatic. Typed appends delegate to the same-module
converters; toString() materialises an owned string.
Constructors
| Type | Method and description |
|---|---|
| constructor() Create an empty builder with a 16-byte backing buffer. |
Method detail
#constructor
Create an empty builder with a 16-byte backing buffer.
Methods
| Type | Method and description |
|---|---|
| _reserve(mut self, extra : i64) : void Grow so extra more bytes fit, doubling the capacity. Thelarger buffer is a fresh i8[]; reassigning self.data freesthe old one. The live prefix is carried across by a counted for into a buffer thatis fresh and unpublished, which hir_passes::idioms::array_idioms lowersto a single non-overlapping memcpy rather than a vectorised loop behinda runtime alias check. A while spelling of the same copy is the onehir_passes::idioms::realloc_idiom recognises( alloc; copy new <- old; free old; publish), so a program that compilesthat shape from source gets one stamped realloc. The shipped stdlib keepsthe explicit copy on purpose: branch_outline moves the growth into thefree function reserve$tail, which a stdlib build never rewrites, becausea fold would withdraw !invariant.load from length loads only in thecompilation that holds it, while a user program reads data.length ofthis same buffer under the claim that the header never changes. The folded form is guarded by realloc_growth_published.axle, the absence here bystring_builder_grow_keeps_its_copy.axle. |
| _pushByte(mut self, b : i32) : void Append one raw byte (low 8 bits of b), growing the buffer if needed. |
| append(mut self, s : string) : StringBuilder Append the bytes of s verbatim (no copy of the source survives the call).Reads s's length through the __string_byte_len compiler builtin(see the note above __stringEquals) rather than the strByteLenFFI shim — on a literal argument (the common case in an append-heavy loop) the header is a compile-time constant, so the inline read folds to that constant instead of surviving as an opaque call; sis a non-nullable string, the same invariant the comparison familyrelies on. |
| appendChar(mut self, c : i32) : StringBuilder Append one Unicode codepoint, UTF-8 encoded. Invalid scalar values (negative, > U+10FFFF, or a surrogate) become U+FFFD, matching the native char::from_u32(..).unwrap_or('\u{FFFD}'). |
| _reverseRange(mut self, lo : i64, hi : i64) : void In-place byte reverse of [lo, hi) — used to flip theleast-significant-first digit run written by _writeI64. |
| _writeI64(mut self, v : i64) : void Format a signed 64-bit integer straight into the buffer — no intermediate string, no FFI, no allocation. Digits come outleast-significant-first then get reversed in place. Works for i64::MIN without overflow: the value is never negated; each v % 10 digit (negative for negative v) is made positivebefore storing, and v is divided toward zero. |
| appendI32(mut self, v : i32) : StringBuilder Append the decimal text of a signed 32-bit value, no intermediate string. |
| appendI64(mut self, v : i64) : StringBuilder Append the decimal text of a signed 64-bit value, no intermediate string. |
| appendF64(mut self, v : f64) : StringBuilder Float formatting (shortest round-trip) stays in the optimised native runtime — reimplementing it in Axle would risk diverging from IEEE round-trip output. |
| appendBool(mut self, v : bool) : StringBuilder Append "true" or "false". |
| length(self) : i32 Character (codepoint) count: every byte that is not a UTF-8 continuation byte ( 0b10xxxxxx) starts a new codepoint. |
| isEmpty(self) : bool True when nothing has been appended (zero bytes buffered). |
| byteLength(self) : i64 Byte length — O(1) (the buffer fill mark). length() countsUTF-8 codepoints and is O(n); use this when you want the raw byte count (e.g. String.length-style or buffer accounting). |
| toString(self) : string Materialise the buffered bytes into a fresh owned string. Thebuilder is left intact and may keep being appended to afterwards. The buffered bytes are copied verbatim, an interior NUL included: the builder's invalidity rules already keep it valid UTF-8, and the length header carries a NUL just as it carries any other byte. bytesToStringperforms exactly one allocation and one copy, so this path is a single alloc + single copy — no intermediate buffer, no second copy. |
| clear(mut self) : StringBuilder Reset to empty, keeping the allocated capacity for reuse. |
| reverse(mut self) : StringBuilder Reverse by codepoint (not by byte) so multi-byte UTF-8 stays valid. Walk the source identifying each char's width from its lead byte, copying whole chars into a scratch buffer back-to-front. |
| dispose(mut self) : void Logical clear. The backing i8[] is reclaimed by thesynthesised destructor when the builder goes out of scope — there is no buffer to release by hand. |
Method detail
#_reserve
Grow so extra more bytes fit, doubling the capacity. The
larger buffer is a fresh i8[]; reassigning self.data frees
the old one.
The live prefix is carried across by a counted for into a buffer that
is fresh and unpublished, which hir_passes::idioms::array_idioms lowers
to a single non-overlapping memcpy rather than a vectorised loop behind
a runtime alias check. A while spelling of the same copy is the onehir_passes::idioms::realloc_idiom recognises
(alloc; copy new <- old; free old; publish), so a program that compiles
that shape from source gets one stamped realloc. The shipped stdlib keeps
the explicit copy on purpose: branch_outline moves the growth into the
free function reserve$tail, which a stdlib build never rewrites, because
a fold would withdraw !invariant.load from length loads only in the
compilation that holds it, while a user program reads data.length of
this same buffer under the claim that the header never changes. The folded
form is guarded by realloc_growth_published.axle, the absence here bystring_builder_grow_keeps_its_copy.axle.
extra number of additional bytes that must fit#_pushByte
Append one raw byte (low 8 bits of b), growing the buffer if needed.
b byte to append (low 8 bits used)#append
Append the bytes of s verbatim (no copy of the source survives the call).
Reads s's length through the __string_byte_len compiler builtin
(see the note above __stringEquals) rather than the strByteLen
FFI shim — on a literal argument (the common case in an append-heavy
loop) the header is a compile-time constant, so the inline read
folds to that constant instead of surviving as an opaque call; s
is a non-nullable string, the same invariant the comparison family
relies on.
s string whose bytes are appended#appendChar
Append one Unicode codepoint, UTF-8 encoded. Invalid scalar
values (negative, > U+10FFFF, or a surrogate) become U+FFFD,
matching the native char::from_u32(..).unwrap_or('\u{FFFD}').
c Unicode codepoint to append#_reverseRange
In-place byte reverse of [lo, hi) — used to flip the
least-significant-first digit run written by _writeI64.
lo inclusive start byte offset of the range to reversehi exclusive end byte offset of the range to reverse#_writeI64
Format a signed 64-bit integer straight into the buffer — no
intermediate string, no FFI, no allocation. Digits come out
least-significant-first then get reversed in place. Works for
i64::MIN without overflow: the value is never negated; eachv % 10 digit (negative for negative v) is made positive
before storing, and v is divided toward zero.
v signed integer to format into the buffer#appendI32
Append the decimal text of a signed 32-bit value, no intermediate string.
v i32 to format and append#appendI64
Append the decimal text of a signed 64-bit value, no intermediate string.
v i64 to format and append#appendF64
Float formatting (shortest round-trip) stays in the optimised
native runtime — reimplementing it in Axle would risk diverging
from IEEE round-trip output.
v f64 to format and append#appendBool
Append "true" or "false".
v bool to format and append#length
Character (codepoint) count: every byte that is not a UTF-8
continuation byte (0b10xxxxxx) starts a new codepoint.
#isEmpty
True when nothing has been appended (zero bytes buffered).
#byteLength
Byte length — O(1) (the buffer fill mark). length() counts
UTF-8 codepoints and is O(n); use this when you want the raw
byte count (e.g. String.length-style or buffer accounting).
#toString
Materialise the buffered bytes into a fresh owned string. The
builder is left intact and may keep being appended to afterwards.
The buffered bytes are copied verbatim, an interior NUL included: the
builder's invalidity rules already keep it valid UTF-8, and the length
header carries a NUL just as it carries any other byte. bytesToString
performs exactly one allocation and one copy, so this path is a single
alloc + single copy — no intermediate buffer, no second copy.
#clear
Reset to empty, keeping the allocated capacity for reuse.
#reverse
Reverse by codepoint (not by byte) so multi-byte UTF-8 stays
valid. Walk the source identifying each char's width from its
lead byte, copying whole chars into a scratch buffer back-to-front.
#dispose
Logical clear. The backing i8[] is reclaimed by the
synthesised destructor when the builder goes out of scope —
there is no buffer to release by hand.