std/text

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

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

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

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

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

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

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

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

#__stringRepeat

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

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

#__stringIsBlank

True when s is empty or contains only Unicode whitespace.

#__stringTrim

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

#__stringTrimStart

Drop leading Unicode whitespace, returning an owned string.

#__stringTrimEnd

Drop trailing Unicode whitespace, returning an owned string.

#__stringToLowerCase

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

#__stringToUpperCase

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

#parseI32

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

#parseI64

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

#parseF64

Parse an IEEE-754 f64, trimming surrounding Unicode whitespace first.

#parseBool

Parse "true" / "false" (after trimming Unicode whitespace).

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

#__txtSubstr

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

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

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

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

#__decodeCodepoint

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

#__txtPutUtf8

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.

#__byteIndexOf

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

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

#__stringLength

Number of UTF-8 characters in s.

#__stringIsEmpty

True when s holds no bytes.

#__stringSubstring

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

#__stringSubstringFrom

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

#__stringStartsWith

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

#__stringEndsWith

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

#__stringContains

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

#__stringIndexOf

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

#__stringLastIndexOf

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

#__stringReplace

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

#__stringReverse

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

#__stringCharAt

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

#__stringPadStart

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

#__stringPadEnd

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

#__stringHashCode

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.

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

#__stringEqualsIgnoreCase

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

#__stringCompare

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

#__i32ToString

Decimal text of a signed 32-bit value.

#__i64ToString

Decimal text of a signed 64-bit value.

#__boolToString

"true" or "false".

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

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

#constructor

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

#_reserve

#_pushByte

#append

#appendChar

#_reverseRange

#_writeI64

#appendI32

#appendI64

#appendF64

#appendBool

#length

#isEmpty

#byteLength

#toString

#clear

#reverse

#dispose