math

import math from "math";

let r: f64 = math.hypot_f64(3.0, 4.0);                 // 5.0
let deg: f64 = math.atan2_f64(1.0, 1.0) * 180.0 / math.PI;   // 45.0
let n: i64 = math.round_f64(2.5) as i64;                // 3

math is pure and freestanding: it imports nothing, allocates nothing and keeps no state, so it works in every profile, t0 kernel code included. It is written in tape; nothing is delegated to a C library.

Naming

A function that exists for several types carries the type as a suffix: sqrt_f64 and sqrt_f32, abs_i64 and abs_i32, min_u64. There is no unsuffixed spelling. A few older integer helpers that exist only for i64 (gcd, lcm, div_ceil, align_up, is_power_of_two) have no suffix.

Floating-point behaviour

Every float function follows IEEE 754 and C’s <math.h> for special values:

• NaN in, NaN out, unless a function says otherwise (pow_f64(x, 0.0) is 1 even for a NaN x; min_f64 and max_f64 ignore a NaN operand).
• Outside the domain (sqrt_f64(-1.0), log_f64(-1.0), asin_f64(2.0)) the result is NaN. A domain error never traps, and there is no error value to check: test with is_nan_f64.
• Overflow gives ±infinity, underflow ±0 or a subnormal.
• Signed zeros are kept: sin_f64(-0.0) is -0.0, sqrt_f64(-0.0) is -0.0.
• A NaN’s sign and payload are unspecified. Compare with is_nan_f64, never by bits.

Accuracy

Results are within the stated error of the exact mathematical value, measured in units in the last place (ULP) of the result. “Exact” means the result is the exact value; 0.5 ULP means correctly rounded.

The f32 functions compute in f64 and round once, so they are almost always correctly rounded. sin, cos and tan reduce their argument exactly, so they stay accurate for arguments of any size (sin_f64(1e22) is right to the last bit).

Every function gives the same bits under tape run and in a native build, and on every platform (apart from the sign and payload of a NaN): the code uses only IEEE arithmetic and integer operations.

Constants

let full_turn: f64 = math.TAU;
let never: bool = math.NAN_F64 == math.NAN_F64;   // false: NaN equals nothing

Classification and sign

is_finite is false for infinities and NaN. abs clears the sign bit and copysign takes x’s magnitude with y’s sign bit, both on NaN too. sign is 1.0 for positive x, −1.0 for negative x, and returns zeros and NaN unchanged.

min, max, clamp, lerp

min and max return the other operand when one is NaN (NaN only when both are), and order −0.0 below +0.0. clamp returns lo when x < lo, hi when x > hi, and x otherwise, so a NaN x stays NaN. lo greater than hi is a bug in the caller: the program stops with a trap (every clamp_*, integer ones too). lerp is a + t * (b - a), exactly a at t = 0 and exactly b at t = 1; t outside 0..1 extrapolates.

Rounding and remainders

All of these are exact. round rounds halfway cases away from zero, like C’s round() (round_f64(0.49999999999999994) is 0.0). fract is x - trunc(x), so it has the sign of x. fmod is x - n*y with n the quotient truncated toward zero, so the result has the sign of x; fmod_f64(x, 0.0) and fmod_f64(±inf, y) are NaN. Infinities and NaN pass through floor, ceil, trunc and round unchanged; fract of an infinity is NaN.

Roots

sqrt is correctly rounded; it is NaN below zero. cbrt is defined for negative numbers. hypot is sqrt(x*x + y*y) without intermediate overflow or underflow, and is +infinity when either argument is infinite, even if the other is NaN.

Trigonometry

Angles are in radians.

sin_f64(math.PI / 6.0) is not exactly 0.5 because math.PI is not exactly π. sin, cos and tan of an infinity are NaN. asin and acos are NaN outside −1..1; asin returns −π/2..π/2, acos 0..π. atan returns −π/2..π/2 and atan2(y, x) the angle of the point (x, y), −π..π, with C’s results for zeros and infinities: atan2_f64(-0.0, -1.0) is −π, atan2_f64(1.0, -math.INF_F64) is π, atan2_f64(math.INF_F64, math.INF_F64) is π/4.

Exponentials and logarithms

exp is e^x and exp2 2^x; both overflow to +infinity and underflow to 0 (exp_f64(-math.INF_F64) is 0), and exp2 of an integer is exact. exp_f64(1.0) is one ULP above E, within the bound. log is the natural logarithm; the logarithms are −infinity at ±0, NaN below zero, and exact (0.0) at 1. log2 of a power of two is exact.

pow follows C99 for special cases:

A negative base with an integer exponent works: pow_f64(-2.0, 3.0) is -8.0.

Integers

Integer arithmetic wraps on overflow, in tape generally (+, - and * work modulo 2^64) and in these helpers (abs_i64 of the most negative value is itself, pow_i64 and pow_u64 wrap). pow_i64 is 1 for exp <= 0. sqrt_i64 is the floor of the square root, 0 for x <= 0; log2_i64 the floor of the base-2 logarithm, −1 for x <= 0. gcd is the non-negative greatest common divisor and gcd(0, 0) is 0; lcm is 0 when either argument is. div_ceil divides rounding toward +infinity for positive b; with b = 0 it divides by zero, which stops the program. align_up needs a power-of-two align.

div_floor_i64 rounds the quotient toward −infinity and mod_floor_i64 is the matching remainder, with the sign of b (Python’s // and %), so a == b * div_floor_i64(a, b) + mod_floor_i64(a, b) always holds. / and % truncate toward zero instead. Both trap for b = 0; div_ceil_u64 too. next_power_of_two_u64 is the smallest power of two >= x (1 for 0) and traps above 2^63, where the answer doesn’t fit.

Checked arithmetic

The result, or null when it doesn’t fit in the type. Use them where an overflow would be a wrong answer (sizes from untrusted input, counters that must not wrap):

let total: ?i64 = math.checked_mul_i64(count, size);
if (total == null) {
    return 1;                                  // too large
}
let bytes: i64 = total!;

Testing

tape test stdlib/math.tape checks every function against reference values computed to high precision, special values, symmetries, and large arguments of the trigonometric functions, in the VM and natively.

Last modified: 2026-10-12 03:08:13 UTC