Library / Numbers / Math / NumericUtilities
NumericUtilities
Methods 13
METHOD floatHashBits(float64 v) RETURNS uint64reads
The hash-stable bit pattern of a float — the value's IEEE-754 binary64 encoding, with one canonicalisation.
A hasher may not simply widen a float into a word: that truncates the mantissa, so two distinct values collide. It takes the BITS instead, which is exact and injective — a float32 key widens into binary64 losslessly first, so both widths share this one path.
-0.0 is the single case where bits and equality disagree: IEEE says
-0.0 == 0.0, so the two MUST hash alike or a dictionary loses a key it
was handed. Both encodings therefore map to 0.
NaN needs no special case and gets none: it is equal to nothing, itself included, so no equal pair can hash differently. The consequence is worth stating plainly — a NaN inserted as a key can never be looked up again. That is IEEE's rule, not this function's.
METHOD toInt32(uint32 v) RETURNS int32reads
Saturating cast uint32 -> int32 (clamps anything above INT32_MAX).
METHOD truncateToUint64(uint128 v) RETURNS uint64reads
Low 64 bits of a 128-bit unsigned value.
METHOD truncateToUint64(int128 v) RETURNS uint64reads
Low 64 bits of a 128-bit SIGNED value (bit-reinterpret; no range check).
The signed sibling of the uint128 form — used by decimal128's cohort hash
and by number's int64↔uint64 reinterpret paths.
METHOD toUint64(int64 v) RETURNS uint64reads
Reinterpret a signed int64 as uint64 (value-preserving for the non-negative
inputs callers guarantee; bit-reinterpret otherwise). The int64 sibling of
toUint64(int32) — number AS uint64 uses it instead of an inline narrow.
METHOD truncateToUint32(uint64 v) RETURNS uint32reads
Low 32 bits of a 64-bit unsigned value.
METHOD truncateToInt32(int64 v) RETURNS int32reads
Low 32 bits of a 64-bit signed value, WRAPPING into int32's range.
Spelled out rather than cast. BAND states which bits are
kept and narrows the type to uint32; the sign is then applied by
arithmetic, because the top half of uint32 has no int32 counterpart and
AS correctly refuses it. Masking the sign bit off first makes the AS
total — it can never fail — and subtracting the bias reproduces two's
complement exactly, in Envzn, with nothing reinterpreted behind the
developer's back.
METHOD truncateToInt32(uint64 v) RETURNS int32reads
Low 32 bits of a 64-bit unsigned value, WRAPPING into int32's range. The unsigned-source sibling of the int64 form above; same construction.
METHOD truncateToInt32(float32 v) RETURNS int32reads
Truncate a float toward zero into int32 (no NaN / range check — the caller is responsible for validating the value first).
There is no total float->int spelling in the language and this host cannot reach the one fallible form: NumericUtilities is emitted BEFORE PrimitiveConversions, so AS/INTO are undeclared identifiers here. TRUNCATE refuses a float source correctly — round-toward-zero is not a bit chop. The shim sits beside ev_convert_f64_to_bits, which this file already binds, so the pattern is the file's own.
METHOD truncateToInt32(float64 v) RETURNS int32reads
METHOD toUint64(int32 v) RETURNS uint64reads
A signed int32 read as uint64 — value-preserving for the non-negative inputs callers guarantee. A NEGATIVE input does not survive: it maps into the top of the unsigned range (-1 becomes 18446744073709551615), so the sign is lost rather than the bits reinterpreted.
METHOD toInt64(uint64 v) RETURNS int64reads
A uint64 read as int64 — value-preserving for values <= INT64_MAX, which
callers guarantee. Above that the value wraps negative. The inverse of
toUint64(int64). It also underpins the uint64 INTO int128 conversion
(PrimitiveConversions), which splits the magnitude across two toInt64 calls
to widen positively — the direct cross-sign assign is not itself a widen.
METHOD exactScaledInt128(int128 mantissa, int32 power) RETURNS | int128reads
Exact integer value of mantissa × 10^power as int128, or FAILURE when the
result is not an exact integer (power < 0 leaving a remainder) or its
magnitude exceeds int128. The shared extraction behind every decimal128 AS
int*/uint*; each caller range-checks the int128 against its own width.