cheatah
Module

math

Scalar math: Python's math module plus the math-flavored built-ins (abs/min/max/pow). Every function is pure and allocation-free — it operates on double / long long by value and never touches the heap.

import io
import math

io.print(math.sqrt(2.0))             # 1.4142135623730951
io.print(math.gcd(48, 18))           # 6
io.print(math.abs(-3), math.max(1, 9, 4)) # 3 9

What's here

  • Constantspi, e, tau, inf, nan.

  • Built-insabs, min, max (variadic), pow.

  • Roots & roundingsqrt, cbrt, fabs, floor, ceil, trunc, round.

  • Exp & logsexp, log, log2, log10.

  • Trigonometrysin, cos, tan, asin, acos, atan, atan2, hypot.

  • Float utilitiesfmod, copysign, degrees, radians, isnan, isinf, isfinite.

  • Integergcd (O(log min)), factorial (O(n)).

Per-function docs (parameters, runtime complexity, heap behavior) are in math.hpp. Tested in ../tests/math_test.cpp; ASan + Valgrind clean via the QA gate (security/run-valgrind.sh).

Functions

fn double sqrt(double x) source#

Square root.

Returns NaN (rather than throwing) for a negative radicand; sqrt(-0.0) is -0.0 and sqrt(+inf) is +inf.

Parameters
x

radicand (NaN if x < 0).

Returns

x.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Sqrt
Performance2.22 ns/call in cheatah · 63.03 ns/call in CPython 3.12.3 · ≈27.6× faster
fn double cbrt(double x) source#

Cube root.

Defined for the whole real line, including negatives (unlike sqrt): the result keeps the sign of x, so cbrt(-8) is -2.

Parameters
x

any real.

Returns

x.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Cbrt
System testStdlibE2E.Math
Performance8.61 ns/call in cheatah · 68.02 ns/call in CPython 3.12.3 · ≈7.9× faster
fn double fabs(double x) source#

Absolute value of a double.

Parameters
x

any real.

Returns

|x|.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Fabs
Performance2.11 ns/call in cheatah · 61.61 ns/call in CPython 3.12.3 · ≈30.4× faster
fn double floor(double x) source#

Round toward −∞.

Returns the largest integral value not greater than x as a double; already-integral, NaN, and ±∞ inputs are returned unchanged, and the sign of zero is preserved.

Parameters
x

any real.

Returns

x⌋.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Floor
System testStdlibE2E.Math
Performance1.88 ns/call in cheatah · 75.29 ns/call in CPython 3.12.3 · ≈39.2× faster
fn double ceil(double x) source#

Round toward +∞.

Returns the smallest integral value not less than x as a double; already-integral, NaN, and ±∞ inputs are returned unchanged. For x in (−1, 0) the result is -0.0.

Parameters
x

any real.

Returns

x⌉.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Ceil
System testStdlibE2E.Math
Performance2.18 ns/call in cheatah · 75.32 ns/call in CPython 3.12.3 · ≈36.6× faster
fn double trunc(double x) source#

Round toward zero.

Discards the fractional part, rounding toward zero rather than ±∞ (so it differs from floor on negatives, e.g. trunc(-2.7) is -2.0); the sign of x, NaN, and ±∞ are preserved.

Parameters
x

any real.

Returns

x with the fraction dropped.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Trunc
System testStdlibE2E.Math
Performance1.89 ns/call in cheatah · 72.04 ns/call in CPython 3.12.3 · ≈38.2× faster
fn double round(double x) source#

Round to nearest (half away from zero).

Halfway cases are rounded away from zero, not to even, so round(2.5) is 3 and round(-2.5) is -3 — this differs from Python's banker's rounding; NaN and ±∞ pass through unchanged.

Parameters
x

any real.

Returns

rounded x.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Round
Performance2.11 ns/call in cheatah · 109 ns/call in CPython 3.12.3 · ≈49.6× faster
fn double exp(double x) source#

Exponential.

Overflows to +inf for large x and underflows to 0 for large negative x; exp(-inf) is 0 and exp(+inf) is +inf.

Parameters
x

any real.

Returns

e^x.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Exp
System testStdlibE2E.Math
Performance3.52 ns/call in cheatah · 65.20 ns/call in CPython 3.12.3 · ≈18.3× faster
fn double log(double x) source#

Natural logarithm.

Returns -inf for x == 0 and NaN (rather than throwing) for negative x; out-of-domain input never raises an exception.

Parameters
x

> 0.

Returns

ln(x).

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Log
System testStdlibE2E.Math
Performance10.57 ns/call in cheatah · 65.08 ns/call in CPython 3.12.3 · ≈6.2× faster
fn double log2(double x) source#

Base-2 logarithm.

Returns -inf for x == 0 and NaN for negative x, matching log's out-of-domain behavior.

Parameters
x

> 0.

Returns

log₂(x).

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Log2
System testStdlibE2E.Math
Performance10.97 ns/call in cheatah · 66.31 ns/call in CPython 3.12.3 · ≈6.1× faster
fn double log10(double x) source#

Base-10 logarithm.

Returns -inf for x == 0 and NaN for negative x, matching log's out-of-domain behavior.

Parameters
x

> 0.

Returns

log₁₀(x).

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Log10
System testStdlibE2E.Math
Performance13.49 ns/call in cheatah · 67.09 ns/call in CPython 3.12.3 · ≈5× faster
fn double sin(double x) source#

Sine.

The argument is interpreted in radians; precision degrades for very large magnitudes due to argument reduction, and sin(±inf) is NaN.

Parameters
x

radians.

Returns

sin(x).

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Sin
System testStdlibE2E.Math
Performance15.20 ns/call in cheatah · 69.69 ns/call in CPython 3.12.3 · ≈4.5× faster
fn double cos(double x) source#

Cosine.

The argument is interpreted in radians; precision degrades for very large magnitudes due to argument reduction, and cos(±inf) is NaN.

Parameters
x

radians.

Returns

cos(x).

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Cos
System testStdlibE2E.Math
Performance15.63 ns/call in cheatah · 71.11 ns/call in CPython 3.12.3 · ≈4.5× faster
fn double tan(double x) source#

Tangent.

The argument is in radians; near the poles (odd multiples of π/2, which are not exactly representable) the result is a large finite value rather than ±∞, and tan(±inf) is NaN.

Parameters
x

radians.

Returns

tan(x).

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Tan
System testStdlibE2E.Math
Performance23.13 ns/call in cheatah · 72.50 ns/call in CPython 3.12.3 · ≈3.1× faster
fn double asin(double x) source#

Arcsine.

Returns a value in [−π/2, π/2]; arguments outside [−1, 1] yield NaN rather than throwing.

Parameters
x

in [−1, 1].

Returns

asin(x) in radians.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Asin
System testStdlibE2E.Math
Performance23.55 ns/call in cheatah · 100 ns/call in CPython 3.12.3 · ≈4.3× faster
fn double acos(double x) source#

Arccosine.

Returns a value in [0, π]; arguments outside [−1, 1] yield NaN rather than throwing.

Parameters
x

in [−1, 1].

Returns

acos(x) in radians.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Acos
System testStdlibE2E.Math
Performance23.36 ns/call in cheatah · 109 ns/call in CPython 3.12.3 · ≈4.3× faster
fn double atan(double x) source#

Arctangent.

Accepts the whole real line and returns a value in (−π/2, π/2), approaching ±π/2 as x → ±∞.

Parameters
x

any real.

Returns

atan(x) in radians.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Atan
System testStdlibE2E.Math
Performance9.79 ns/call in cheatah · 63.81 ns/call in CPython 3.12.3 · ≈6.5× faster
fn double atan2(double y, double x) source#

Two-argument arctangent.

Uses the signs of both arguments to select the correct quadrant, returning a value in (−π, π]; it is well-defined when x is zero (including the atan2(0, 0) case, which returns 0).

Parameters
y, x

the coordinates.

Returns

atan2(y, x) in radians.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Atan2
System testStdlibE2E.Math
Performance9.17 ns/call in cheatah · 72.73 ns/call in CPython 3.12.3 · ≈8× faster
fn double hypot(double x, double y) source#

Hypotenuse.

Computes the 2-norm while avoiding intermediate overflow/underflow that a naive sqrt(x*x + y*y) would suffer; returns +inf if either argument is infinite (even when the other is NaN).

Parameters
x, y

the legs.

Returns

√(x²+) without overflow.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Hypot
System testStdlibE2E.Math
Performance8.99 ns/call in cheatah · 82.18 ns/call in CPython 3.12.3 · ≈9.3× faster
fn double fmod(double x, double y) source#

Floating-point remainder.

Returns x - n*y for the integer n truncated toward zero, so the result takes the sign of the dividend x (unlike a Python-style modulo); a zero divisor yields NaN rather than throwing.

Parameters
x, y

dividend, divisor.

Returns

x mod y.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Fmod
System testStdlibE2E.Math
Performance5.36 ns/call in cheatah · 64.93 ns/call in CPython 3.12.3 · ≈12.1× faster
fn double copysign(double x, double y) source#

Copy sign.

Takes the magnitude from x and the sign bit from y; because it copies the IEEE sign bit, it distinguishes +0.0 from -0.0 and works even when x is NaN.

Parameters
x

magnitude source,

y

sign source.

Returns

|x| with y's sign.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Copysign
System testStdlibE2E.Math
Performance2.00 ns/call in cheatah · 62.41 ns/call in CPython 3.12.3 · ≈32.7× faster
fn double degrees(double radians) source#

Radians → degrees.

Parameters
radians

angle in radians.

Returns

the angle in degrees.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Degrees
System testStdlibE2E.Math
Performance2.07 ns/call in cheatah · 58.43 ns/call in CPython 3.12.3 · ≈29.4× faster
fn double radians(double degrees) source#

Degrees → radians.

Parameters
degrees

angle in degrees.

Returns

the angle in radians.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Radians
System testStdlibE2E.Math
Performance2.07 ns/call in cheatah · 58.82 ns/call in CPython 3.12.3 · ≈28.6× faster
fn bool isnan(double x) source#

Is NaN?

The reliable NaN test, since NaN compares unequal to everything including itself (so x != x is the only other portable check).

Parameters
x

any real.

Returns

true iff x is NaN.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Isnan
System testStdlibE2E.Math
Performance0.91 ns/call in cheatah · 59.49 ns/call in CPython 3.12.3 · ≈65.6× faster
fn bool isinf(double x) source#

Is infinite?

True for both +inf and -inf; false for NaN (use isnan for that) and for every finite value.

Parameters
x

any real.

Returns

true iff x is ±∞.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Isinf
System testStdlibE2E.Math
Performance0.90 ns/call in cheatah · 60.40 ns/call in CPython 3.12.3 · ≈66.9× faster
fn bool isfinite(double x) source#

Is finite?

Parameters
x

any real.

Returns

true iff x is neither NaN nor ±∞.

Complexity

O(1).

Allocation

none.

Compile-run testMathCompileRun.Isfinite
System testStdlibE2E.Math
Performance2.09 ns/call in cheatah · 62.23 ns/call in CPython 3.12.3 · ≈29.9× faster
fn long long gcd(long long a, long long b) source#

Greatest common divisor.

Operates on the absolute values via the Euclidean algorithm, so the result is non-negative; gcd(0, 0) is 0 and gcd(n, 0) is |n|. Passing LLONG_MIN overflows when negated.

Parameters
a, b

integers.

Returns

gcd(|a|, |b|).

Complexity

O(log min(a,b)) time.

Allocation

none.

Compile-run testMathCompileRun.Gcd
System testStdlibE2E.Math
Performance5.85 ns/call in cheatah · 89.30 ns/call in CPython 3.12.3 · ≈15.2× faster
fn long long factorial(long long n) source#

Factorial.

Computed by an iterative product from 2; n of 0 or 1 returns 1, and any negative n also returns 1 since the loop never executes (no error is raised). Results past 20! silently overflow long long.

Parameters
n

≥ 0 (small; overflows long long past 20!).

Returns

n!.

Complexity

O(n) time.

Allocation

none.

Compile-run testMathCompileRun.Factorial
System testStdlibE2E.Math
Performance3.95 ns/call in cheatah · 57.50 ns/call in CPython 3.12.3 · ≈14.2× faster
fn T abs(T x) source#

Absolute value.

Parameters
x

any signed value.

Returns

|x|.

Complexity

O(1) time.

Allocation

none.

Warning

For a signed integer type the most-negative value cannot be negated: abs of it overflows (undefined behavior).

Compile-run testMathCompileRun.Abs
System testStdlibE2E.Math
Performance0.86 ns/call in cheatah · 62.82 ns/call in CPython 3.12.3 · ≈80.2× faster
fn min · 2 overloads
const T & min(const T &a, const T &b)source#
const T & min(const T &a, const T &b, const Rest &... rest)source#

Smallest of two-or-more values (variadic; the overloads chain to fold extra args).

Returns a reference bound to whichever argument compares smaller; on a tie (neither b < a) it returns a. Because the result is a reference into the caller's arguments, it dangles when the operands are temporaries.

Parameters
a, b

the values to compare (operator< required).

Returns

a reference to the minimum.

Complexity

O(n) in the argument count.

Allocation

none.

Compile-run testMathCompileRun.Min
Performance0.60 ns/call in cheatah · 123 ns/call in CPython 3.12.3 · ≈207× faster
fn max · 2 overloads
const T & max(const T &a, const T &b)source#
const T & max(const T &a, const T &b, const Rest &... rest)source#

Largest of two-or-more values (variadic; the overloads chain to fold extra args).

Returns a reference bound to whichever argument compares larger; on a tie (neither a < b) it returns a. As with min, the returned reference dangles if the operands are temporaries.

Parameters
a, b

the values to compare (operator< required).

Returns

a reference to the maximum.

Complexity

O(n) in the argument count.

Allocation

none.

Compile-run testMathCompileRun.Max
Performance0.70 ns/call in cheatah · 117 ns/call in CPython 3.12.3 · ≈169.6× faster
fn double pow(Base base, Exp exp) source#

Power.

Both operands are cast to double and forwarded to std::pow, so this follows IEEE-754 semantics (e.g. pow(0, 0) is 1, and a negative base with a non-integer exponent yields NaN); integer arguments lose exactness beyond 2^53.

Parameters
base

the base.

exp

the exponent.

Returns

base raised to exp (computed as double).

Complexity

O(1) time.

Allocation

none.

Compile-run testMathCompileRun.Pow
System testStdlibE2E.Math
Performance0.69 ns/call in cheatah · 73.99 ns/call in CPython 3.12.3 · ≈107.2× faster

Constants & variables

var double pi source#

π.

var double e source#

Euler's number e.

var double tau source#

τ = 2π.

var double inf source#

+∞.

var double nan source#

quiet NaN.