Axle v0.22.0
Package

std/text

std/text — string operations and parsing.

Free functions over the primitive string type, backing the
string 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 the
byteAt 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

TypeMethod and description
string
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 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.
string
stringFromBytesRaw(buf : ptr, len : i64) : string The total byte bridge: copy len bytes from a raw buffer into an owned
string, 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.
string
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 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].
string
bytesToStringStrict(buf : i8[], len : i64) : string 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.
ptr<i8>
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 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.
i64
bufferAddr(buf : i8[]) : i64 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.
bool
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 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.
ptr
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 a
buffer rather than its base.

Here, and only here, so the i64 -> ptr decay has one site the way
bufferPtr 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.
i32
__stringByteAt(s : string, i : i64) : i32 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.
string
__string_concat(a : string, b : string) : string Runtime helper backing a + b when either operand is a string. The
result is a fresh owned string; the operands are left untouched.
string
__stringRepeat(s : string, n : i32) : string s repeated n times ("" when n <= 0). Builds the result in a
single allocation filled in place — no scratch buffer, no re-copy.
string
__stringConcat(a : string, b : string) : string 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).
bool
__stringIsBlank(s : string) : bool True when s is empty or contains only Unicode whitespace.
string
__stringTrim(s : string) : string Drop leading and trailing Unicode whitespace, returning an owned string.
string
__stringTrimStart(s : string) : string Drop leading Unicode whitespace, returning an owned string.
string
__stringTrimEnd(s : string) : string Drop trailing Unicode whitespace, returning an owned string.
string
__stringToLowerCase(s : string) : string Full Unicode lowercase folding (locale-independent), as an owned string.
string
__stringToUpperCase(s : string) : string Full Unicode uppercase folding (locale-independent), as an owned string.
i32
parseI32(s : string) : i32 Parse a base-10 i32, trimming surrounding Unicode whitespace first.
i64
parseI64(s : string) : i64 Parse a base-10 i64, trimming surrounding Unicode whitespace first.
u32
parseU32(s : string) : u32 Parse a base-10 u32, trimming surrounding Unicode whitespace first.
A leading - is refused, -0 included.
u64
parseU64(s : string) : u64 Parse a base-10 u64, trimming surrounding Unicode whitespace first.
A leading - is refused, -0 included.
f64
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 and
an exponent too large for f64 are refused rather than answered as the
non-finite value they would produce.
bool
parseBool(s : string) : bool 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.
i32
__stringToI32(s : string) : i32 s.toI32() — @throws ParseException when the text is not a 32-bit integer.
i64
__stringToI64(s : string) : i64 s.toI64() — @throws ParseException when the text is not a 64-bit integer.
f64
__stringToF64(s : string) : f64 s.toF64() — @throws ParseException when the text is not a float literal.
bool
__stringToBool(s : string) : bool s.toBool() — @throws ParseException for anything but "true" / "false".
string
__f64ToString(v : f64) : string IEEE-754 shortest round-trip text of v (the value parseF64 inverts).
string
__txtSubstr(s : string, start : i64, end : i64) : string Copy bytes [start, end) of s into an owned string.
i32
__charCountPrefix(s : string, byteEnd : i64) : i32 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 made
length / indexOf / substring O(n) function calls on the length).
i64
__charByteIndex(s : string, srcLen : i64, charIdx : i32) : i64 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.
i64
__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.
i32
__decodeCodepoint(s : string, byteOffset : i64) : i32 Decode the Unicode codepoint of the character starting at
byteOffset (assumed valid UTF-8).
i64
__txtPutUtf8(buffer : ptr<i8>, offset : i64, codepoint : i32) : i64 UTF-8 encode codepoint (invalid scalars folded to U+FFFD, matching
char::from_u32(..).unwrap_or(..)) into buffer at offset,
returning the offset past the bytes written.
i64
__byteIndexOf(s : string, sourceLen : i64, sub : string, subLen : i64, from : i64) : i64 Byte offset of the first occurrence of sub in s at or after
from, or -1. An empty needle matches at from (mirrors
str::find("")).
string
__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).
i32
__stringLength(s : string) : i32 Number of UTF-8 characters in s.
bool
__stringIsEmpty(s : string) : bool True when s holds no bytes.
string
__stringSubstring(s : string, start : i32, end : i32) : string Substring of the characters [start, end). Raises
IndexOutOfBoundsException when the range is negative, inverted, or
past the character count.
string
__stringSubstringFrom(s : string, start : i32) : string Substring from character start to the end. Raises
IndexOutOfBoundsException when start is negative or past the
character count.
bool
__stringStartsWith(s : string, prefix : string) : bool True when s begins with prefix (byte comparison; empty prefix is always true).
bool
__stringEndsWith(s : string, suffix : string) : bool True when s ends with suffix (byte comparison; empty suffix is always true).
bool
__stringContains(s : string, sub : string) : bool True when sub occurs anywhere in s (empty sub always matches).
i32
__stringIndexOf(s : string, sub : string) : i32 Character index of the first occurrence of sub, or -1.
i32
__stringLastIndexOf(s : string, sub : string) : i32 Character index of the last occurrence of sub, or -1.
string
__stringReplace(s : string, from : string, to : string) : string Replace every non-overlapping occurrence of from with to. An
empty from inserts to around every character (mirroring
str::replace).
string
__stringReverse(s : string) : string Reverse by character (not by byte) so multi-byte UTF-8 stays valid.
i32
__stringCharAt(s : string, i : i32) : i32 Unicode codepoint at character index i, or -1 if out of range.
string
__stringPadStart(s : string, len : i32, c : i32) : string Pad s on the left with character c until it spans len
characters (no-op when already at least that long).
string
__stringPadEnd(s : string, len : i32, c : i32) : string Pad s on the right with character c until it spans len
characters (no-op when already at least that long).
i32
__stringHashCode(s : string) : i32 31-polynomial hash over the codepoints: h = 31*h + c, wrapping in
i32 (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.
bool
__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 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.
bool
__stringEqualsIgnoreCase(a : string, b : string) : bool ASCII case-insensitive equality (only A-Z ↔ a-z are folded,
matching eq_ignore_ascii_case).
i32
__stringCompare(a : string, b : string) : i32 Lexicographic byte comparison: <0, 0, >0. A proper prefix sorts
before the longer string.
string
__i32ToString(v : i32) : string Decimal text of a signed 32-bit value.
string
__i64ToString(v : i64) : string Decimal text of a signed 64-bit value.
string
__boolToString(v : bool) : string "true" or "false".
string
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() is
the spelling most code reaches for; this is the same formatter under a
name a module can use.
string
f64ToString(v : f64) : string 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.
string
__f32ToString(v : f32) : string v.toString() on an out-of-range f32 — the primitive-method entry for
f32, rendering through the f64 formatter. Every f32 widens to f64
exactly, so the shortest f64 round-trip text is the shortest f32 one.
string
__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 formatter
renders them exactly.
string
__u16ToString(v : u16) : string v.toString() — @param v u16 to render in base 10.
string
__u32ToString(v : u32) : string v.toString() — @param v u32 to render in base 10.
string
__u64ToString(v : u64) : string 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.

Method detail

#stringFromBytes

stringFromBytes(buf : ptr, len : i64) : string ! IllegalArgumentException

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.

Parameters
buf raw source buffer to copy from
len number of bytes to copy out of buf
Throws
IllegalArgumentException when the bytes hold an interior NUL.

#stringFromBytesRaw

stringFromBytesRaw(buf : ptr, len : i64) : string

The total byte bridge: copy len bytes from a raw buffer into an owned
string, 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.

Parameters
buf raw source buffer to copy from
len number of bytes to copy out of buf

#bytesToString

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 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].

Parameters
buf byte array whose contents are copied
len number of bytes to read from buf

#bytesToStringStrict

bytesToStringStrict(buf : i8[], len : i64) : string ! IllegalArgumentException

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.

Parameters
buf byte array whose contents are copied
len number of bytes to read from buf
Throws
IllegalArgumentException when the bytes hold an interior NUL.

#bufferPtr

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 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.

Parameters
buf byte array whose base address is taken

#bufferAddr

bufferAddr(buf : i8[]) : i64

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.

Parameters
buf byte array whose base address is taken

#spanFits

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 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.

Parameters
buf the array the window is taken from
offset first index of the window
len window length in bytes

#addrAsPtr

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 a
buffer rather than its base.

Here, and only here, so the i64 -> ptr decay has one site the way
bufferPtr 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.

Parameters
addr base address, from bufferAddr, plus any byte offset

#__stringByteAt

__stringByteAt(s : string, i : i64) : i32

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.

Parameters
s string to read
i byte offset into s, 0-based

#__string_concat

__string_concat(a : string, b : string) : string

Runtime helper backing a + b when either operand is a string. The
result is a fresh owned string; the operands are left untouched.

Parameters
a left operand, placed first in the result
b right operand, appended after a

#__stringRepeat

__stringRepeat(s : string, n : i32) : string

s repeated n times ("" when n <= 0). Builds the result in a
single allocation filled in place — no scratch buffer, no re-copy.

Parameters
s string to repeat
n number of repetitions

#__stringConcat

__stringConcat(a : string, b : string) : string

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).

Parameters
a left operand, placed first in the result
b right operand, appended after a

#__stringIsBlank

__stringIsBlank(s : string) : bool

True when s is empty or contains only Unicode whitespace.

Parameters
s string to test for blankness

#__stringTrim

__stringTrim(s : string) : string

Drop leading and trailing Unicode whitespace, returning an owned string.

Parameters
s string to trim on both ends

#__stringTrimStart

__stringTrimStart(s : string) : string

Drop leading Unicode whitespace, returning an owned string.

Parameters
s string to trim on the leading end

#__stringTrimEnd

__stringTrimEnd(s : string) : string

Drop trailing Unicode whitespace, returning an owned string.

Parameters
s string to trim on the trailing end

#__stringToLowerCase

__stringToLowerCase(s : string) : string

Full Unicode lowercase folding (locale-independent), as an owned string.

Parameters
s string to lowercase

#__stringToUpperCase

__stringToUpperCase(s : string) : string

Full Unicode uppercase folding (locale-independent), as an owned string.

Parameters
s string to uppercase

#parseI32

parseI32(s : string) : i32 ! ParseException

Parse a base-10 i32, trimming surrounding Unicode whitespace first.

Parameters
s decimal text to parse
Throws
ParseException when the text is empty or not a valid 32-bit integer.

#parseI64

parseI64(s : string) : i64 ! ParseException

Parse a base-10 i64, trimming surrounding Unicode whitespace first.

Parameters
s decimal text to parse
Throws
ParseException when the text is empty or not a valid 64-bit integer.

#parseU32

parseU32(s : string) : u32 ! ParseException

Parse a base-10 u32, trimming surrounding Unicode whitespace first.
A leading - is refused, -0 included.

Parameters
s decimal text to parse
Throws
ParseException when the text is empty, negative or not a valid 32-bit unsigned integer.

#parseU64

parseU64(s : string) : u64 ! ParseException

Parse a base-10 u64, trimming surrounding Unicode whitespace first.
A leading - is refused, -0 included.

Parameters
s decimal text to parse
Throws
ParseException when the text is empty, negative or not a valid 64-bit unsigned integer.

#parseF64

parseF64(s : string) : f64 ! ParseException

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.

Parameters
s floating-point text to parse
Throws
ParseException when the text is not a finite float literal.

#parseBool

parseBool(s : string) : bool ! ParseException

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.

Parameters
s bool text to parse
Throws
ParseException for any other text.

#__stringToI32

__stringToI32(s : string) : i32 ! ParseException

s.toI32() — @throws ParseException when the text is not a 32-bit integer.

#__stringToI64

__stringToI64(s : string) : i64 ! ParseException

s.toI64() — @throws ParseException when the text is not a 64-bit integer.

#__stringToF64

__stringToF64(s : string) : f64 ! ParseException

s.toF64() — @throws ParseException when the text is not a float literal.

#__stringToBool

__stringToBool(s : string) : bool ! ParseException

s.toBool() — @throws ParseException for anything but "true" / "false".

#__f64ToString

__f64ToString(v : f64) : string

IEEE-754 shortest round-trip text of v (the value parseF64 inverts).

Parameters
v f64 to render

#__txtSubstr

__txtSubstr(s : string, start : i64, end : i64) : string

Copy bytes [start, end) of s into an owned string.

Parameters
s source string
start inclusive start byte offset into s, 0-based
end exclusive end byte offset into s

#__charCountPrefix

__charCountPrefix(s : string, byteEnd : i64) : i32

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 made
length / indexOf / substring O(n) function calls on the length).

Parameters
s source string
byteEnd exclusive end byte offset of the prefix to count

#__charByteIndex

__charByteIndex(s : string, srcLen : i64, charIdx : i32) : i64

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.

Parameters
s source string
srcLen byte length of s
charIdx character index to locate, 0-based

#__charWidth

__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.

Parameters
lead lead byte of a UTF-8 sequence

#__decodeCodepoint

__decodeCodepoint(s : string, byteOffset : i64) : i32

Decode the Unicode codepoint of the character starting at
byteOffset (assumed valid UTF-8).

Parameters
s source string
byteOffset byte offset of the character's lead byte

#__txtPutUtf8

__txtPutUtf8(buffer : ptr<i8>, offset : i64, codepoint : i32) : i64

UTF-8 encode codepoint (invalid scalars folded to U+FFFD, matching
char::from_u32(..).unwrap_or(..)) into buffer at offset,
returning the offset past the bytes written.

Parameters
buffer destination buffer base address
offset byte offset at which to write the encoded bytes
codepoint Unicode scalar to encode

#__byteIndexOf

__byteIndexOf(s : string, sourceLen : i64, sub : string, subLen : i64, from : i64) : i64

Byte offset of the first occurrence of sub in s at or after
from, or -1. An empty needle matches at from (mirrors
str::find("")).

Parameters
s haystack string
sourceLen byte length of s
sub needle substring to search for
subLen byte length of sub
from byte offset at which the search starts

#__txtFormatDecimal

__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).

Parameters
v signed integer to render in base 10

#__stringLength

__stringLength(s : string) : i32

Number of UTF-8 characters in s.

Parameters
s string to measure

#__stringIsEmpty

__stringIsEmpty(s : string) : bool

True when s holds no bytes.

Parameters
s string to test for emptiness

#__stringSubstring

__stringSubstring(s : string, start : i32, end : i32) : string ! IndexOutOfBoundsException

Substring of the characters [start, end). Raises
IndexOutOfBoundsException when the range is negative, inverted, or
past the character count.

Parameters
s source string
start inclusive start character index, 0-based
end exclusive end character index

#__stringSubstringFrom

__stringSubstringFrom(s : string, start : i32) : string ! IndexOutOfBoundsException

Substring from character start to the end. Raises
IndexOutOfBoundsException when start is negative or past the
character count.

Parameters
s source string
start inclusive start character index, 0-based

#__stringStartsWith

__stringStartsWith(s : string, prefix : string) : bool

True when s begins with prefix (byte comparison; empty prefix is always true).

Parameters
s string to test
prefix candidate leading substring

#__stringEndsWith

__stringEndsWith(s : string, suffix : string) : bool

True when s ends with suffix (byte comparison; empty suffix is always true).

Parameters
s string to test
suffix candidate trailing substring

#__stringContains

__stringContains(s : string, sub : string) : bool

True when sub occurs anywhere in s (empty sub always matches).

Parameters
s haystack string
sub needle substring to search for

#__stringIndexOf

__stringIndexOf(s : string, sub : string) : i32

Character index of the first occurrence of sub, or -1.

Parameters
s haystack string
sub needle substring to search for

#__stringLastIndexOf

__stringLastIndexOf(s : string, sub : string) : i32

Character index of the last occurrence of sub, or -1.

Parameters
s haystack string
sub needle substring to search for

#__stringReplace

__stringReplace(s : string, from : string, to : string) : string

Replace every non-overlapping occurrence of from with to. An
empty from inserts to around every character (mirroring
str::replace).

Parameters
s source string
from substring to search for and replace
to replacement substring

#__stringReverse

__stringReverse(s : string) : string

Reverse by character (not by byte) so multi-byte UTF-8 stays valid.

Parameters
s string to reverse

#__stringCharAt

__stringCharAt(s : string, i : i32) : i32

Unicode codepoint at character index i, or -1 if out of range.

Parameters
s source string
i character index, 0-based

#__stringPadStart

__stringPadStart(s : string, len : i32, c : i32) : string

Pad s on the left with character c until it spans len
characters (no-op when already at least that long).

Parameters
s string to pad
len target length in characters
c Unicode codepoint of the pad character

#__stringPadEnd

__stringPadEnd(s : string, len : i32, c : i32) : string

Pad s on the right with character c until it spans len
characters (no-op when already at least that long).

Parameters
s string to pad
len target length in characters
c Unicode codepoint of the pad character

#__stringHashCode

__stringHashCode(s : string) : i32

31-polynomial hash over the codepoints: h = 31*h + c, wrapping in
i32 (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.

Parameters
s string to hash

#__stringEquals

__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 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.

Parameters
a first string to compare
b second string to compare

#__stringEqualsIgnoreCase

__stringEqualsIgnoreCase(a : string, b : string) : bool

ASCII case-insensitive equality (only A-Z ↔ a-z are folded,
matching eq_ignore_ascii_case).

Parameters
a first string to compare
b second string to compare

#__stringCompare

__stringCompare(a : string, b : string) : i32

Lexicographic byte comparison: <0, 0, >0. A proper prefix sorts
before the longer string.

Parameters
a left operand of the comparison
b right operand of the comparison

#__i32ToString

__i32ToString(v : i32) : string

Decimal text of a signed 32-bit value.

Parameters
v i32 to render in base 10

#__i64ToString

__i64ToString(v : i64) : string

Decimal text of a signed 64-bit value.

Parameters
v i64 to render in base 10

#__boolToString

__boolToString(v : bool) : string

"true" or "false".

Parameters
v bool to render

#i64ToString

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() is
the spelling most code reaches for; this is the same formatter under a
name a module can use.

Parameters
v i64 to render in base 10

#f64ToString

f64ToString(v : f64) : string

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.

Parameters
v f64 to render

#__f32ToString

__f32ToString(v : f32) : string

v.toString() on an out-of-range f32 — the primitive-method entry for
f32, rendering through the f64 formatter. Every f32 widens to f64
exactly, so the shortest f64 round-trip text is the shortest f32 one.

Parameters
v f32 to render

#__u8ToString

__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 formatter
renders them exactly.

Parameters
v u8 to render in base 10

#__u16ToString

__u16ToString(v : u16) : string

v.toString() — @param v u16 to render in base 10.

#__u32ToString

__u32ToString(v : u32) : string

v.toString() — @param v u32 to render in base 10.

#__u64ToString

__u64ToString(v : u64) : string

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.

Parameters
v u64 to render in base 10

C 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

TypeMethod and description
constructor() Create an empty builder with a 16-byte backing buffer.

Method detail

#constructor

constructor()

Create an empty builder with a 16-byte backing buffer.

Methods

TypeMethod and description
void
_reserve(mut self, extra : i64) : void 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 one
hir_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 by
string_builder_grow_keeps_its_copy.axle.
void
_pushByte(mut self, b : i32) : void Append one raw byte (low 8 bits of b), growing the buffer if needed.
StringBuilder
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 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.
StringBuilder
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}').
void
_reverseRange(mut self, lo : i64, hi : i64) : void In-place byte reverse of [lo, hi) — used to flip the
least-significant-first digit run written by _writeI64.
void
_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 out
least-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 positive
before storing, and v is divided toward zero.
StringBuilder
appendI32(mut self, v : i32) : StringBuilder Append the decimal text of a signed 32-bit value, no intermediate string.
StringBuilder
appendI64(mut self, v : i64) : StringBuilder Append the decimal text of a signed 64-bit value, no intermediate string.
StringBuilder
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.
StringBuilder
appendBool(mut self, v : bool) : StringBuilder Append "true" or "false".
i32
length(self) : i32 Character (codepoint) count: every byte that is not a UTF-8
continuation byte (0b10xxxxxx) starts a new codepoint.
bool
isEmpty(self) : bool True when nothing has been appended (zero bytes buffered).
i64
byteLength(self) : i64 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).
string
toString(self) : string 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.
StringBuilder
clear(mut self) : StringBuilder Reset to empty, keeping the allocated capacity for reuse.
StringBuilder
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.
void
dispose(mut self) : void 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.

Method detail

#_reserve

_reserve(mut self, extra : i64) : void

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 one
hir_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 by
string_builder_grow_keeps_its_copy.axle.

Parameters
extra number of additional bytes that must fit

#_pushByte

_pushByte(mut self, b : i32) : void

Append one raw byte (low 8 bits of b), growing the buffer if needed.

Parameters
b byte to append (low 8 bits used)

#append

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 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.

Parameters
s string whose bytes are appended

#appendChar

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}').

Parameters
c Unicode codepoint to append

#_reverseRange

_reverseRange(mut self, lo : i64, hi : i64) : void

In-place byte reverse of [lo, hi) — used to flip the
least-significant-first digit run written by _writeI64.

Parameters
lo inclusive start byte offset of the range to reverse
hi exclusive end byte offset of the range to reverse

#_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 out
least-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 positive
before storing, and v is divided toward zero.

Parameters
v signed integer to format into the buffer

#appendI32

appendI32(mut self, v : i32) : StringBuilder

Append the decimal text of a signed 32-bit value, no intermediate string.

Parameters
v i32 to format and append

#appendI64

appendI64(mut self, v : i64) : StringBuilder

Append the decimal text of a signed 64-bit value, no intermediate string.

Parameters
v i64 to format and append

#appendF64

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.

Parameters
v f64 to format and append

#appendBool

appendBool(mut self, v : bool) : StringBuilder

Append "true" or "false".

Parameters
v bool to format and append

#length

length(self) : i32

Character (codepoint) count: every byte that is not a UTF-8
continuation byte (0b10xxxxxx) starts a new codepoint.

#isEmpty

isEmpty(self) : bool

True when nothing has been appended (zero bytes buffered).

#byteLength

byteLength(self) : i64

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

toString(self) : string

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

clear(mut self) : StringBuilder

Reset to empty, keeping the allocated capacity for reuse.

#reverse

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

dispose(mut self) : void

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.