vercel-labs--zerolang/docs/articles/modules/math.md

When To Use std.math

In Zerolang, use std.math for pure fixed-width integer helpers, checked/saturating arithmetic, and small number-theory routines.

Runnable today:

API	Return	Notes
std.math.minU32(left, right)	u32	Returns the smaller unsigned value.
std.math.minI32(left, right)	i32	Returns the smaller signed 32-bit value.
std.math.minUsize(left, right)	usize	Returns the smaller pointer-width unsigned value.
std.math.minI64(left, right)	i64	Returns the smaller signed 64-bit value.
std.math.minU64(left, right)	u64	Returns the smaller unsigned 64-bit value.
std.math.maxU32(left, right)	u32	Returns the larger unsigned value.
std.math.maxI32(left, right)	i32	Returns the larger signed 32-bit value.
std.math.maxUsize(left, right)	usize	Returns the larger pointer-width unsigned value.
std.math.maxI64(left, right)	i64	Returns the larger signed 64-bit value.
std.math.maxU64(left, right)	u64	Returns the larger unsigned 64-bit value.
std.math.clampU32(value, low, high)	u32	Clamps between the two bounds; swapped bounds are normalized.
std.math.clampI32(value, low, high)	i32	Clamps a signed 32-bit value; swapped bounds are normalized.
std.math.clampUsize(value, low, high)	usize	Clamps a pointer-width unsigned value; swapped bounds are normalized.
std.math.clampI64(value, low, high)	i64	Clamps a signed 64-bit value; swapped bounds are normalized.
std.math.clampU64(value, low, high)	u64	Clamps an unsigned 64-bit value; swapped bounds are normalized.
std.math.absI32(value)	u32	Returns the unsigned magnitude of a signed 32-bit value.
std.math.absI64(value)	u64	Returns the unsigned magnitude of a signed 64-bit value.
std.math.checkedAddU32(left, right)	Maybe<u32>	Adds only when the result fits in u32.
std.math.checkedSubU32(left, right)	Maybe<u32>	Subtracts only when the result fits in u32.
std.math.checkedMulU32(left, right)	Maybe<u32>	Multiplies only when the result fits in u32.
std.math.checkedAddUsize(left, right)	Maybe<usize>	Adds only when the result fits in usize.
std.math.checkedSubUsize(left, right)	Maybe<usize>	Subtracts only when the result fits in usize.
std.math.checkedMulUsize(left, right)	Maybe<usize>	Multiplies only when the result fits in usize.
std.math.checkedAddI32(left, right)	Maybe<i32>	Adds only when the result fits in i32.
std.math.checkedSubI32(left, right)	Maybe<i32>	Subtracts only when the result fits in i32.
std.math.checkedMulI32(left, right)	Maybe<i32>	Multiplies only when the result fits in i32.
std.math.saturatingAddU32(left, right)	u32	Adds and clamps overflow to u32 max.
std.math.saturatingSubU32(left, right)	u32	Subtracts and clamps underflow to 0.
std.math.saturatingMulU32(left, right)	u32	Multiplies and clamps overflow to u32 max.
std.math.saturatingAddUsize(left, right)	usize	Adds and clamps overflow to usize max.
std.math.saturatingSubUsize(left, right)	usize	Subtracts and clamps underflow to 0.
std.math.saturatingMulUsize(left, right)	usize	Multiplies and clamps overflow to usize max.
std.math.saturatingAddI32(left, right)	i32	Adds and clamps overflow to the nearest i32 bound.
std.math.saturatingSubI32(left, right)	i32	Subtracts and clamps overflow to the nearest i32 bound.
std.math.saturatingMulI32(left, right)	i32	Multiplies and clamps overflow to the nearest i32 bound.
std.math.gcdU32(left, right)	u32	Euclidean greatest common divisor.
std.math.lcmU32(left, right)	u32	Least common multiple; returns 0 when either input is 0.
std.math.checkedLcmU32(left, right)	Maybe<u32>	Least common multiple only when the result fits in u32.
std.math.powU32(base, exponent)	u32	Fixed-width exponentiation by squaring.
std.math.checkedPowU32(base, exponent)	Maybe<u32>	Exponentiation only when the result fits in u32.
std.math.modPowU32(base, exponent, modulus)	u32	Modular exponentiation; returns 0 for modulus 0.
std.math.isPrimeU32(value)	Bool	Trial division primality for unsigned integers.
std.math.isEvenU32(value)	Bool	Reports whether a u32 value is even.
std.math.isOddU32(value)	Bool	Reports whether a u32 value is odd.
std.math.sqrtFloorU32(value)	u32	Integer square root rounded down.
std.math.factorialU32(value)	Maybe<u32>	Factorial only when the result fits in u32.
std.math.binomialU32(n, k)	Maybe<u32>	Binomial coefficient only when the result fits in u32.
std.math.divisorCountU32(value)	u32	Counts positive divisors; returns 0 for 0.
std.math.properDivisorSumU32(value)	u32	Sums positive divisors smaller than value.

Current scope:

• Helpers are pure, target-neutral fixed-width integer operations.
• Checked helpers return Maybe<T> instead of wrapping or trapping.
• Saturating helpers clamp to documented integer bounds.
• The module does not provide floating-point math, big integers, or arbitrary-precision number theory.

Example

pub fn main(world: World) -> Void raises {
    if std.math.gcdU32(84, 30) == 6 && std.math.isPrimeU32(31) {
        check world.out.write("math helper ok\n")
    }
}

Design Notes

std.math does not allocate and does not require a hosted runtime capability. Names include the integer width because Zero does not overload standard-library helpers by argument type.

Number-theory helpers are intentionally simple and deterministic. They are suitable for small fixed-width tasks, examples, and compiler-portable checks. Large-number algorithms should be added as explicit APIs with documented bounds instead of hidden heap allocation or implicit widening.