envzn
0.8 · beta · not released

Library / Numbers / Math / NumericUtilities

CLASS

NumericUtilities

Methods 13

METHOD floatHashBits(float64 v) RETURNS uint64
reads

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 int32
reads

Saturating cast uint32 -> int32 (clamps anything above INT32_MAX).

METHOD truncateToUint64(uint128 v) RETURNS uint64
reads

Low 64 bits of a 128-bit unsigned value.

METHOD truncateToUint64(int128 v) RETURNS uint64
reads

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 uint64
reads

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 uint32
reads

Low 32 bits of a 64-bit unsigned value.

METHOD truncateToInt32(int64 v) RETURNS int32
reads

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 int32
reads

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 int32
reads

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 int32
reads
METHOD toUint64(int32 v) RETURNS uint64
reads

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 int64
reads

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 | int128
reads

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.