wehub-resource-sync
e7738de6d2
CI / Deep Native Runtime Cases (1/6) (push) Has been skipped
CI / Native Preflight (push) Failing after 1s
CI / Native Runtime Cases (1/2) (push) Failing after 0s
CI / Native Runtime Cases (2/2) (push) Failing after 1s
CI / Native Metadata Reports (push) Failing after 0s
CI / Native Direct Backend Artifacts (push) Failing after 0s
CI / Native Sanitizer Smoke (push) Failing after 1s
CI / Command Contract Snapshots (push) Failing after 1s
CI / Deep Conformance Suite (push) Has been skipped
CI / Graph Build Perf (push) Failing after 1s
CI / Deep Native Preflight (push) Has been skipped
CI / Deep Native Runtime Cases (2/6) (push) Has been skipped
CI / Deep Native Runtime Cases (3/6) (push) Has been skipped
CI / Conformance Suite (push) Failing after 1s
CI / Workspace Checks (push) Failing after 0s
CI / Deep Native Runtime Cases (5/6) (push) Has been skipped
CI / Deep Native Runtime Cases (6/6) (push) Has been skipped
CI / Deep Native Runtime Cases (4/6) (push) Has been skipped
CI / Deep Graph Build Perf (push) Has been skipped
87 lines
5.9 KiB
Markdown
87 lines
5.9 KiB
Markdown
## 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
|
|
|
|
```zero
|
|
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.
|