Axle v0.22.0
Package

std/text/boxing

std/boxing — i32 / i64 radix conversions, plus the Float / Char
conversion facades.

i32 and i64 decimal parsing, decimal rendering, and IEEE
classification all resolve through the primitive method surface
(s.toI32(), v.toString(), …) or the std/numeric/math bounds
(math::i32Min(), …) — nothing here duplicates them. The radix
(binary / hex) rendering is a method on the value for every integer
width (v.toHex() / v.toBin()), backed by the free functions
below; what has no method row is the parse-with-explicit-base form,
since the base is a second subject.

f32 and char are admitted by the primitive-receiver gate
(hir_builder::…::calls::method), so their value operations are
methods too — x.sqrt(), c.toI32(). The Float and Char facades
keep only what has no receiver to hang on: the producers parse /
fromI32 / min / max, and the f32 special constants.

Pure Axle end to end — no native shim. The IEEE parser / formatter for
f64 are the runtime-backed primitives of std/text (parseF64 /
f64ToString), reached here by cross-module use (Float round-trips
through them). The radix formatters, radix parser, and the Float
special constants (materialised from their exact IEEE bit patterns via
__f32FromBits) are computed in Axle.

Free functions

TypeMethod and description
string
__formatBinary(value : i64, width : i32) : string Binary text (no leading zeros, no 0b) of the low width bits of
value. The caller masks value to the unsigned interpretation it
wants; bit i is read as (value >> i) & 1, which is correct for
i < width regardless of the shift's sign behaviour.
string
__formatHex(value : i64, nibbles : i32) : string Lowercase hex text (no leading zeros) of the low nibbles * 4 bits
of value.
string
__formatOctal(value : i64, groups : i32) : string Octal text (no leading zeros) of the low groups * 3 bits of
value.
string
__i32ToHex(v : i32) : string v.toHex() — lowercase hex text of v's unsigned 32-bit interpretation.
string
__i32ToBin(v : i32) : string v.toBin() — binary text of v's unsigned 32-bit interpretation
(no 0b).
string
__i32ToOct(v : i32) : string v.toOct() — octal text of v's unsigned 32-bit interpretation.
string
__i64ToHex(v : i64) : string v.toHex() — lowercase hex text of v's unsigned 64-bit interpretation.
string
__i64ToBin(v : i64) : string v.toBin() — binary text of v's unsigned 64-bit interpretation
(no 0b).
string
__u8ToHex(v : u8) : string v.toHex() — lowercase hex of v's 8-bit interpretation.
string
__u8ToBin(v : u8) : string v.toBin() — binary of v's 8-bit interpretation (no 0b).
string
__u16ToHex(v : u16) : string v.toHex() — lowercase hex of v's 16-bit interpretation.
string
__u16ToBin(v : u16) : string v.toBin() — binary of v's 16-bit interpretation (no 0b).
string
__u32ToHex(v : u32) : string v.toHex() — lowercase hex of v's 32-bit interpretation.
string
__u32ToBin(v : u32) : string v.toBin() — binary of v's 32-bit interpretation (no 0b).
string
__u64ToHex(v : u64) : string v.toHex() — lowercase hex of v's 64-bit interpretation.
string
__u64ToBin(v : u64) : string v.toBin() — binary of v's 64-bit interpretation (no 0b).
i64
__parseRadix(s : string, base : i32) : i64 Parse s as a signed integer in base (2..=36), accepting an
optional leading + / -. Digits are 0..9 then a..z
(case-insensitive) for values 10..35. Accumulates in i64 so
[parseI32Base] can range-check the wide result before narrowing.

Text too long for an i64 throws rather than wrapping. Axle's + and
* wrap, so an unguarded acc * base + d turns "99999999999999999999"
into an arbitrary in-range number — and parseI32Base's own range check
then approves it, because by the time it looks the value is already
inside the range. A parse that cannot represent its input must say so.
i32
parseI32Base(s : string, base : i32) : i32 Parse s in an arbitrary base (2..=36) as an i32; narrows after a
range check. Free function, not a method: the base is a second
meaningful argument, not incidental context, so parseI32Base(s, base)
reads at least as clearly as a method would and needs no primitive-
method table row.
i64
parseI64Base(s : string, base : i32) : i64 Parse s in an arbitrary base (2..=36) as an i64.
i32
__charToI32(c : char) : i32 The i32 codepoint of c — a char and an i32 are both 4-byte
stack slots, so reading c's address back as ptr<i32> recovers
the exact codepoint with no lossy round trip (unlike the IEEE bit
tricks above, this reinterpret IS the value: a char's storage
representation is its Unicode scalar value).
char
__i32ToCharUnchecked(cp : i32) : char The char whose codepoint is cp, with no scalar-value
validation — private helper for call sites that already proved
cp is a valid Unicode scalar value (e.g. read back from a real
string's charAt). [Char::fromI32] is the validating public
entry point.
bool
__isValidScalarValue(cp : i32) : bool true when cp is a valid Unicode scalar value: in range
[0, 0x10FFFF] and not a surrogate ([0xD800, 0xDFFF] is reserved
for UTF-16 encoding and never a scalar value on its own). Mirrors
the range check StringBuilder::appendChar uses to fall back to
U+FFFD.
string
__charToString(c : char) : string One-character text of c.
bool
__charIsDigit(c : char) : bool true for an ASCII decimal digit ('0'..'9').
bool
__charIsWhitespace(c : char) : bool true for Unicode whitespace — delegates to string's Unicode-aware blank
test rather than re-implementing the classification table.
char
__charToUpperCase(c : char) : char Unicode uppercase of c. When the fold changes the character count (e.g.
German ß → "SS"), c has no single-character uppercase form and is
returned unchanged.
char
__charToLowerCase(c : char) : char Unicode lowercase of c. Returned unchanged when the fold changes the
character count.

Method detail

#__formatBinary

__formatBinary(value : i64, width : i32) : string

Binary text (no leading zeros, no 0b) of the low width bits of
value. The caller masks value to the unsigned interpretation it
wants; bit i is read as (value >> i) & 1, which is correct for
i < width regardless of the shift's sign behaviour.

Parameters
value bit pattern to render, low width bits significant
width number of low bits to render

#__formatHex

__formatHex(value : i64, nibbles : i32) : string

Lowercase hex text (no leading zeros) of the low nibbles * 4 bits
of value.

Parameters
value bit pattern to render, low nibbles * 4 bits significant
nibbles number of 4-bit hex digits to render

#__formatOctal

__formatOctal(value : i64, groups : i32) : string

Octal text (no leading zeros) of the low groups * 3 bits of
value.

Parameters
value bit pattern to render, low groups * 3 bits significant
groups number of 3-bit octal digits to render

#__i32ToHex

__i32ToHex(v : i32) : string

v.toHex() — lowercase hex text of v's unsigned 32-bit interpretation.

Parameters
v i32 to render, read as unsigned 32-bit

#__i32ToBin

__i32ToBin(v : i32) : string

v.toBin() — binary text of v's unsigned 32-bit interpretation
(no 0b).

Parameters
v i32 to render, read as unsigned 32-bit

#__i32ToOct

__i32ToOct(v : i32) : string

v.toOct() — octal text of v's unsigned 32-bit interpretation.

Parameters
v i32 to render, read as unsigned 32-bit

#__i64ToHex

__i64ToHex(v : i64) : string

v.toHex() — lowercase hex text of v's unsigned 64-bit interpretation.

Parameters
v i64 to render, read as unsigned 64-bit

#__i64ToBin

__i64ToBin(v : i64) : string

v.toBin() — binary text of v's unsigned 64-bit interpretation
(no 0b).

Parameters
v i64 to render, read as unsigned 64-bit

#__u8ToHex

__u8ToHex(v : u8) : string

v.toHex() — lowercase hex of v's 8-bit interpretation.

#__u8ToBin

__u8ToBin(v : u8) : string

v.toBin() — binary of v's 8-bit interpretation (no 0b).

#__u16ToHex

__u16ToHex(v : u16) : string

v.toHex() — lowercase hex of v's 16-bit interpretation.

#__u16ToBin

__u16ToBin(v : u16) : string

v.toBin() — binary of v's 16-bit interpretation (no 0b).

#__u32ToHex

__u32ToHex(v : u32) : string

v.toHex() — lowercase hex of v's 32-bit interpretation.

#__u32ToBin

__u32ToBin(v : u32) : string

v.toBin() — binary of v's 32-bit interpretation (no 0b).

#__u64ToHex

__u64ToHex(v : u64) : string

v.toHex() — lowercase hex of v's 64-bit interpretation.

#__u64ToBin

__u64ToBin(v : u64) : string

v.toBin() — binary of v's 64-bit interpretation (no 0b).

#__parseRadix

__parseRadix(s : string, base : i32) : i64 ! ParseException

Parse s as a signed integer in base (2..=36), accepting an
optional leading + / -. Digits are 0..9 then a..z
(case-insensitive) for values 10..35. Accumulates in i64 so
[parseI32Base] can range-check the wide result before narrowing.

Text too long for an i64 throws rather than wrapping. Axle's + and
* wrap, so an unguarded acc * base + d turns "99999999999999999999"
into an arbitrary in-range number — and parseI32Base's own range check
then approves it, because by the time it looks the value is already
inside the range. A parse that cannot represent its input must say so.

Parameters
s text to parse, optional leading + / - then digits
base radix, 2..=36

#parseI32Base

parseI32Base(s : string, base : i32) : i32 ! ParseException

Parse s in an arbitrary base (2..=36) as an i32; narrows after a
range check. Free function, not a method: the base is a second
meaningful argument, not incidental context, so parseI32Base(s, base)
reads at least as clearly as a method would and needs no primitive-
method table row.

Parameters
s text to parse in the given radix
base radix, 2..=36

#parseI64Base

parseI64Base(s : string, base : i32) : i64 ! ParseException

Parse s in an arbitrary base (2..=36) as an i64.

Parameters
s text to parse in the given radix
base radix, 2..=36

#__charToI32

__charToI32(c : char) : i32

The i32 codepoint of c — a char and an i32 are both 4-byte
stack slots, so reading c's address back as ptr<i32> recovers
the exact codepoint with no lossy round trip (unlike the IEEE bit
tricks above, this reinterpret IS the value: a char's storage
representation is its Unicode scalar value).

Parameters
c char whose codepoint is read out

#__i32ToCharUnchecked

__i32ToCharUnchecked(cp : i32) : char

The char whose codepoint is cp, with no scalar-value
validation — private helper for call sites that already proved
cp is a valid Unicode scalar value (e.g. read back from a real
string's charAt). [Char::fromI32] is the validating public
entry point.

Parameters
cp codepoint to reinterpret as a char

#__isValidScalarValue

__isValidScalarValue(cp : i32) : bool

true when cp is a valid Unicode scalar value: in range
[0, 0x10FFFF] and not a surrogate ([0xD800, 0xDFFF] is reserved
for UTF-16 encoding and never a scalar value on its own). Mirrors
the range check StringBuilder::appendChar uses to fall back to
U+FFFD.

Parameters
cp candidate codepoint

#__charToString

__charToString(c : char) : string

One-character text of c.

Parameters
c char to render

#__charIsDigit

__charIsDigit(c : char) : bool

true for an ASCII decimal digit ('0'..'9').

Parameters
c char to classify

#__charIsWhitespace

__charIsWhitespace(c : char) : bool

true for Unicode whitespace — delegates to string's Unicode-aware blank
test rather than re-implementing the classification table.

Parameters
c char to classify

#__charToUpperCase

__charToUpperCase(c : char) : char

Unicode uppercase of c. When the fold changes the character count (e.g.
German ß → "SS"), c has no single-character uppercase form and is
returned unchanged.

Parameters
c char to fold

#__charToLowerCase

__charToLowerCase(c : char) : char

Unicode lowercase of c. Returned unchanged when the fold changes the
character count.

Parameters
c char to fold

C class Float

Static-utility facade for f32. The value operations of an f32
are methods on the value — v.toString(), x.isNaN(), x.sqrt(),
x.abs() — resolving through the primitive-method table onto the
__f32* free functions in std/numeric/math and std/numeric/ieee.
What stays here is what has no receiver: the parse producer and
the special constants, which name no particular value. Parsing
round-trips through the f64 primitives (no dedicated
single-precision parser exists, and narrowing f64 as f32 is always
accepted); the constants are materialised from their exact 32-bit
patterns.

Methods

TypeMethod and description
f32
parse(s : string) : f32 IEEE-754 parse, trimming Unicode whitespace. Parses as f64
then narrows — a narrowing f64 as f32 is always accepted (only
the lossy float→int direction is gated).
string
toString(v : f32) : string Shortest round-trip IEEE-754 text of v, via the f64
formatter (widening f32 → f64 is exact — every f32 value is
representable in f64).
bool
isNaN(v : f32) : bool true when v is NaN — exponent all ones and a mantissa that is not
zero. Read off the encoding, for the reason std/numeric/ieee states.
bool
isInfinite(v : f32) : bool true for ±infinity — exponent all ones, mantissa zero, either sign.
bool
isFinite(v : f32) : bool true for a finite value — anything the exponent does not saturate.
f32
min() : f32 Smallest positive normal f32.
f32
max() : f32 Largest finite f32.
f32
positiveInfinity() : f32 +∞.
f32
negativeInfinity() : f32 -∞. Its pattern 0xFF800000 sets the sign bit, so it can't be
an i32 hex literal directly — the two's complement of
0x00800000 is exactly that pattern.
f32
notANumber() : f32 A quiet NaN.

Method detail

#parse

parse(s : string) : f32 ! ParseException

IEEE-754 parse, trimming Unicode whitespace. Parses as f64
then narrows — a narrowing f64 as f32 is always accepted (only
the lossy float→int direction is gated).

Parameters
s floating-point text to parse

#toString

toString(v : f32) : string

Shortest round-trip IEEE-754 text of v, via the f64
formatter (widening f32 → f64 is exact — every f32 value is
representable in f64).

Parameters
v f32 to render

#isNaN

isNaN(v : f32) : bool

true when v is NaN — exponent all ones and a mantissa that is not
zero. Read off the encoding, for the reason std/numeric/ieee states.

Parameters
v f32 to classify

#isInfinite

isInfinite(v : f32) : bool

true for ±infinity — exponent all ones, mantissa zero, either sign.

Parameters
v f32 to classify

#isFinite

isFinite(v : f32) : bool

true for a finite value — anything the exponent does not saturate.

Parameters
v f32 to classify

#min

min() : f32

Smallest positive normal f32.

#max

max() : f32

Largest finite f32.

#positiveInfinity

positiveInfinity() : f32

+∞.

#negativeInfinity

negativeInfinity() : f32

-∞. Its pattern 0xFF800000 sets the sign bit, so it can't be
an i32 hex literal directly — the two's complement of
0x00800000 is exactly that pattern.

#notANumber

notANumber() : f32

A quiet NaN.

C class Char

Static-utility facade for char — a char is a 32-bit Unicode
scalar value, distinct from the plain i32 codepoints string's
per-character surface (charAt / appendChar) uses. The value
operations are methods on the value — c.toI32(), c.isDigit(),
c.toUpperCase() — resolving through the primitive-method table onto
the __char* free functions above; each method body delegates to
that same function, so the two spellings cannot answer differently.
What stays here is the producers: fromI32 (the inverse of toI32),
parse, and the min / max bounds. The conversions between the
two forms are a same-width pointer-reinterpret, and every char
operation composes on the existing Unicode-aware string primitives
(case fold, blank test) rather than re-implementing Unicode
classification.

Methods

TypeMethod and description
i32
toI32(c : char) : i32 The Unicode codepoint of c, as a plain i32 — the same value
"…".charAt(i) would report for this character.
char
fromI32(cp : i32) : char The char whose codepoint is cp.
char
parse(s : string) : char Parse a single-character string into a char.
string
toString(c : char) : string One-character text of c.
char
min() : char Smallest char (the NUL scalar value, U+0000).
char
max() : char Largest char (the highest Unicode scalar value, U+10FFFF).
bool
isDigit(c : char) : bool true for an ASCII decimal digit ('0'..'9').
bool
isWhitespace(c : char) : bool true for Unicode whitespace — delegates to string's
Unicode-aware blank test rather than re-implementing the
classification table.
char
toUpperCase(c : char) : char Unicode uppercase of c, via string's case fold. When the
fold changes the character count (e.g. German ß → "SS"),
c has no single-character uppercase form and is returned
unchanged.
char
toLowerCase(c : char) : char Unicode lowercase of c, via string's case fold. Returned
unchanged when the fold changes the character count.

Method detail

#toI32

toI32(c : char) : i32

The Unicode codepoint of c, as a plain i32 — the same value
"…".charAt(i) would report for this character.

Parameters
c char to read the codepoint of

#fromI32

fromI32(cp : i32) : char ! IllegalArgumentException

The char whose codepoint is cp.

Parameters
cp Unicode codepoint, must be a valid scalar value

#parse

parse(s : string) : char ! ParseException

Parse a single-character string into a char.

Parameters
s text that must hold exactly one character

#toString

toString(c : char) : string

One-character text of c.

Parameters
c char to render

#min

min() : char

Smallest char (the NUL scalar value, U+0000).

#max

max() : char

Largest char (the highest Unicode scalar value, U+10FFFF).

#isDigit

isDigit(c : char) : bool

true for an ASCII decimal digit ('0'..'9').

Parameters
c char to classify

#isWhitespace

isWhitespace(c : char) : bool

true for Unicode whitespace — delegates to string's
Unicode-aware blank test rather than re-implementing the
classification table.

Parameters
c char to classify

#toUpperCase

toUpperCase(c : char) : char

Unicode uppercase of c, via string's case fold. When the
fold changes the character count (e.g. German ß → "SS"),
c has no single-character uppercase form and is returned
unchanged.

Parameters
c char to fold

#toLowerCase

toLowerCase(c : char) : char

Unicode lowercase of c, via string's case fold. Returned
unchanged when the fold changes the character count.

Parameters
c char to fold