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.