math
Numeric utilities over CX int and float scalar kinds. Covers basic arithmetic and rounding, powers/logs/roots, trigonometry and hyperbolics, statistics, bit operations, numeric predicates, number theory, special constants, and explicit modular arithmetic. Every function is pure. Real-valued functions return NaN on domain errors per IEEE 754 rather than raising, while int64 arithmetic is checked by default with wrapping-* as the opt-in modular escape hatch.
math:abs
[$math:abs] -> any — Return the absolute value, preserving the operand's numeric kind.
[?lib 'cx-stdlib/math']
[$math:abs -5]
5
math:sign
[$math:sign] -> int — Return -1, 0, or 1 for the sign of a number.
[?lib 'cx-stdlib/math']
[$math:sign -7]
-1
math:floor
[$math:floor] -> int — Round a float down to the nearest integer (toward negative infinity).
[?lib 'cx-stdlib/math']
[$math:floor 2.7]
2
math:ceiling
[$math:ceiling] -> int — Round a float up to the nearest integer (toward positive infinity).
[?lib 'cx-stdlib/math']
[$math:ceiling 2.1]
3
math:round
[$math:round] -> int — Round a float to the nearest integer using banker's rounding (half-to-even).
[?lib 'cx-stdlib/math']
[$math:round 0.5e0]
0
math:round-half-up
[$math:round-half-up] -> int — Round a float to the nearest integer, ties going half-away-from-zero.
[?lib 'cx-stdlib/math']
[$math:round-half-up 0.5e0]
1
math:round-half-even
[$math:round-half-even] -> int — Round a float to the nearest integer using half-to-even; explicit alias for round.
[?lib 'cx-stdlib/math']
[$math:round-half-even 2.5e0]
2
math:round-to
[$math:round-to] -> any — Round to the given number of decimal places, keeping the kind: a float answers a float, a decimal rounds exactly to a decimal, an int stays an int; an optional {mode: …} takes the div-decimal rounding modes.
[?lib 'cx-stdlib/math']
[$math:round-to 3.14159e0 2]
3.14e0
math:round-sig
[$math:round-sig] (x::any, figures::int, opts::map) -> any — Round to N significant figures, keeping the kind: the exact value rounds at its own decimal exponent (a carry keeps N figures), half away from zero unless {mode: …} names a div-decimal mode.
[?lib 'cx-stdlib/math']
[$math:round-sig 1.23456e24 5]
1.2346e24
math:truncate
[$math:truncate] -> int — Truncate a float toward zero, discarding the fractional part.
[?lib 'cx-stdlib/math']
[$math:truncate -2.9e0]
-2
math:max
[$math:max] -> any — Return the largest value in a sequence.
[?lib 'cx-stdlib/math']
[$math:max (3, 7, 2, 9, 1)]
9
math:min
[$math:min] -> any — Return the smallest value in a sequence.
[?lib 'cx-stdlib/math']
[$math:min (3, 7, 2, 9, 1)]
1
math:clamp
[$math:clamp] -> any — Constrain a value to the inclusive range between lo and hi.
[?lib 'cx-stdlib/math']
[$math:clamp 5 0 10]
5
math:pow
[$math:pow] -> any — Raise base to the power of exp. An int or bigint base to a non-negative int exp answers the exact power — an int while it fits int64, a bigint past it; a negative exp or a float operand answers a float.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:pow 2.0e0 1.0e1] 0]
1.024e3
[?lib 'cx-stdlib/math']
([$math:pow 3 4], [$math:pow 2 63], [$math:pow 2 -1])
(81, 9223372036854775808, 5.0e-1)
math:sqrt
[$math:sqrt] -> float — Return the square root; negative input yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:sqrt 1.6e1] 0]
4.0e0
math:cbrt
[$math:cbrt] -> float — Return the cube root, defined for negative input.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:cbrt 2.7e1] 0]
3.0e0
math:sqrt-decimal
[$math:sqrt-decimal] (x::any, ctx::map) -> decimal — The square root of an exact operand (int, bigint or decimal) as a decimal, rounded under the div-decimal context: {scale: N mode: …} for N digits after the point, {precision: N mode: …} for N significant digits; every mode rounds the exact root.
[?lib 'cx-stdlib/math']
[$math:sqrt-decimal 2 {scale: 10, mode: :down}]
1.4142135623
math:hypot
[$math:hypot] (x::float, y::float, *more) -> float — The Euclidean length of two or more coordinates (Python's math.hypot), scaled by a power of two so the squares neither overflow nor underflow.
[?lib 'cx-stdlib/math']
[$math:hypot 3.0e0 4.0e0]
5.0e0
math:exp
[$math:exp] -> float — Return e raised to the power of x.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:exp 0.0e0] 0]
1.0e0
math:log
[$math:log] -> float — Return the natural (base-e) logarithm; non-positive input yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:log [$math:e]] 8]
1.0e0
math:log2
[$math:log2] -> float — Return the base-2 logarithm; non-positive input yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:log2 1.024e3] 0]
1.0e1
math:log10
[$math:log10] -> float — Return the base-10 logarithm; non-positive input yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:log10 1.0e2] 0]
2.0e0
math:log-base
[$math:log-base] -> float — Return the logarithm of x in an arbitrary base.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:log-base 8.1e1 3.0e0] 0]
4.0e0
math:sin
[$math:sin] -> float — Return the sine of an angle in radians.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:sin 0.0e0] 0]
0.0e0
math:cos
[$math:cos] -> float — Return the cosine of an angle in radians.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:cos 0.0e0] 0]
1.0e0
math:tan
[$math:tan] -> float — Return the tangent of an angle in radians.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:tan [$math:round-to [$math:pi] 15]] 8]
0.0e0
math:asin
[$math:asin] -> float — Return the arcsine in radians; input outside -1..1 yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:asin 0.0e0] 0]
0.0e0
math:acos
[$math:acos] -> float — Return the arccosine in radians; input outside -1..1 yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:acos 1.0e0] 0]
0.0e0
math:atan
[$math:atan] -> float — Return the arctangent in radians.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:atan 0.0e0] 0]
0.0e0
math:atan2
[$math:atan2] -> float — Return the angle in radians of the point (x, y), respecting quadrant.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:atan2 1.0e0 1.0e0] 8]
7.8539816e-1
math:sinh
[$math:sinh] -> float — Return the hyperbolic sine of x.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:sinh 0.0e0] 0]
0.0e0
math:cosh
[$math:cosh] -> float — Return the hyperbolic cosine of x.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:cosh 0.0e0] 0]
1.0e0
math:tanh
[$math:tanh] -> float — Return the hyperbolic tangent of x.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:tanh 0.0e0] 0]
0.0e0
math:asinh
[$math:asinh] -> float — Return the inverse hyperbolic sine of x.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:asinh 0.0e0] 0]
0.0e0
math:acosh
[$math:acosh] -> float — Return the inverse hyperbolic cosine of x; input below 1 yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:acosh 1.0e0] 0]
0.0e0
math:atanh
[$math:atanh] -> float — Return the inverse hyperbolic tangent of x; input outside -1..1 yields NaN.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:atanh 0.0e0] 0]
0.0e0
math:deg-to-rad
[$math:deg-to-rad] -> float — Convert an angle from degrees to radians.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:deg-to-rad 1.8e2] 8]
3.14159265e0
math:rad-to-deg
[$math:rad-to-deg] -> float — Convert an angle from radians to degrees.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:rad-to-deg [$math:pi]] 0]
1.8e2
math:sum
[$math:sum] -> any — Return the sum of a sequence of numbers; the empty sequence answers the int 0.
[?lib 'cx-stdlib/math']
[$math:sum (1, 2, 3, 4, 5)]
15
math:product
[$math:product] -> any — Return the product of a sequence of numbers; the empty sequence answers the int 1.
[?lib 'cx-stdlib/math']
[$math:product (1, 2, 3, 4, 5)]
120
math:mean
[$math:mean] -> any — Return the arithmetic mean of a sequence — a float over ints and floats, exact over decimals and bigints (as $avg); empty input raises.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:mean (2, 4, 6)] 1]
4.0e0
math:median
[$math:median] -> any — Return the median of a sequence: the middle member itself, in its own kind, for an odd count; for an even count the float mean of the two middle members over ints and floats, their exact half-sum over decimals and bigints; empty input raises.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:median (3, 1, 2)] 1]
2
math:mode
[$math:mode] -> any — Return the most-frequent value; ties resolve to the smallest tied value.
[?lib 'cx-stdlib/math']
[$math:mode (1, 2, 2, 3, 3, 3)]
3
math:multimode
[$math:multimode] -> [sequence any] — Return all values tied at the maximum frequency, sorted ascending.
[?lib 'cx-stdlib/math']
[$math:multimode (5, 5, 2, 2)]
(2, 5)
math:stddev
[$math:stddev] -> float — Return the sample standard deviation (N-1) of a sequence.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:stddev (2, 4, 4, 4, 5, 5, 7, 9)] 4]
2.1381e0
math:variance
[$math:variance] -> float — Return the sample variance (N-1) of a sequence.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:variance (2, 4, 4, 4, 5, 5, 7, 9)] 4]
4.5714e0
math:stddev-pop
[$math:stddev-pop] -> float — Return the population standard deviation (N) of a sequence.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:stddev-pop (2, 4, 4, 4, 5, 5, 7, 9)] 1]
2.0e0
math:variance-pop
[$math:variance-pop] -> float — Return the population variance (N) of a sequence.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:variance-pop (2, 4, 4, 4, 5, 5, 7, 9)] 1]
4.0e0
math:percentile
[$math:percentile] -> float — Return the p-th percentile of a sequence, with p in 0..100.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:percentile (1, 2, 3, 4, 5) 5.0e1] 1]
3.0e0
math:quantile
[$math:quantile] -> float — Return the q-th quantile of a sequence, with q in 0..1.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:quantile (1, 2, 3, 4, 5) 0.5e0] 1]
3.0e0
math:correlation
[$math:correlation] -> float — Return the Pearson correlation coefficient between two sequences.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:correlation (1.0e0, 2.0e0, 3.0e0, 4.0e0, 5.0e0, 6.0e0, 7.0e0, 8.0e0, 9.0e0, 1.0e1) (2.0e0, 4.0e0, 6.0e0, 8.0e0, 1.0e1, 1.2e1, 1.4e1, 1.6e1, 1.8e1, 2.0e1)] 1]
1.0e0
math:covariance
[$math:covariance] -> float — Return the sample covariance (N-1) between two sequences.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:covariance (1.0e0, 2.0e0, 3.0e0, 4.0e0, 5.0e0) (2.0e0, 4.0e0, 6.0e0, 8.0e0, 1.0e1)] 1]
5.0e0
math:bit-and
[$math:bit-and] -> int — Return the bitwise AND of two integers — int64, or a bigint exactly in two's complement.
[?lib 'cx-stdlib/math']
[$math:bit-and 255 15]
15
math:bit-or
[$math:bit-or] -> int — Return the bitwise OR of two integers — int64, or a bigint exactly in two's complement.
[?lib 'cx-stdlib/math']
[$math:bit-or 240 15]
255
math:bit-xor
[$math:bit-xor] -> int — Return the bitwise XOR of two integers — int64, or a bigint exactly in two's complement.
[?lib 'cx-stdlib/math']
[$math:bit-xor 255 15]
240
math:bit-not
[$math:bit-not] -> int — Return the bitwise complement of an integer (-x - 1), int64 or bigint.
[?lib 'cx-stdlib/math']
[$math:bit-not 0]
-1
math:bit-shift-left
[$math:bit-shift-left] -> int — Shift bits left by n, checked: a result that leaves int64 refuses CXER3000 (wrapping-shift-left wraps); a bigint shifts exactly; zero shifts to zero; a negative count raises.
[?lib 'cx-stdlib/math']
[$math:bit-shift-left 1 4]
16
math:bit-shift-right
[$math:bit-shift-right] -> int — Arithmetic (sign-extending, floored) right shift by n, over int and bigint; count of 64 or more saturates an int, negative count raises.
[?lib 'cx-stdlib/math']
[$math:bit-shift-right -8 1]
-4
math:popcount
[$math:popcount] -> int — Count the set bits in a 64-bit integer, or in a non-negative bigint; a negative bigint past int64 refuses CXER3003.
[?lib 'cx-stdlib/math']
[$math:popcount 255]
8
math:leading-zeros
[$math:leading-zeros] -> int — Count the leading zero bits in a 64-bit integer (a bigint that fits int64 counts as that int); a bigint past int64 refuses CXER3003 — bit-length is its width.
[?lib 'cx-stdlib/math']
[$math:leading-zeros 1]
63
math:trailing-zeros
[$math:trailing-zeros] -> int — Count the trailing zero bits in an integer, int64 or bigint; zero answers 64.
[?lib 'cx-stdlib/math']
[$math:trailing-zeros 8]
3
math:bit-length
[$math:bit-length] -> int — The number of bits in the magnitude of an integer (Python's int.bit_length): 0 for 0, int or bigint.
[?lib 'cx-stdlib/math']
[$math:bit-length 7]
3
math:ilog2
[$math:ilog2] -> int — The exact integer log2, floor(log2 n), of an integer n >= 1, int or bigint; n < 1 refuses CXER3003.
[?lib 'cx-stdlib/math']
[$math:ilog2 1024]
10
math:is-nan
[$math:is-nan] -> bool — Report whether a value is IEEE 754 NaN.
[?lib 'cx-stdlib/math']
[$math:is-nan [$math:log -1.0e0]]
true
math:is-infinite
[$math:is-infinite] -> bool — Report whether a value is positive or negative infinity.
[?lib 'cx-stdlib/math']
[$math:is-infinite [$math:infinity]]
true
math:is-finite
[$math:is-finite] -> bool — Report whether a value is finite (not NaN or infinity).
[?lib 'cx-stdlib/math']
[$math:is-finite 3.5e0]
true
math:is-integer
[$math:is-integer] -> bool — Report whether a value has no fractional part.
[?lib 'cx-stdlib/math']
[$math:is-integer 4.0e0]
true
math:is-positive
[$math:is-positive] -> bool — Report whether a value is greater than zero.
[?lib 'cx-stdlib/math']
[$math:is-positive 3]
true
math:is-negative
[$math:is-negative] -> bool — Report whether a value is less than zero.
[?lib 'cx-stdlib/math']
[$math:is-negative -3]
true
math:is-zero
[$math:is-zero] -> bool — Report whether a value is exactly zero.
[?lib 'cx-stdlib/math']
[$math:is-zero 0]
true
math:is-close
[$math:is-close] (a::float, b::float, opts::map) -> bool — Approximate float comparison (Python's math.isclose): close when the difference is within rel-tol of the larger magnitude or within abs-tol; the options map names rel-tol (default 1e-9) and abs-tol (default 0).
[?lib 'cx-stdlib/math']
[$math:is-close 1.0e0 1.0000000001e0]
true
math:gcd
[$math:gcd] -> int — Return the greatest common divisor of two integers.
[?lib 'cx-stdlib/math']
[$math:gcd 12 18]
6
math:lcm
[$math:lcm] -> int — Return the least common multiple of two integers.
[?lib 'cx-stdlib/math']
[$math:lcm 4 6]
12
math:is-prime
[$math:is-prime] -> bool — Report whether an integer is prime, exact across the full int64 range.
[?lib 'cx-stdlib/math']
[$math:is-prime 97]
true
math:factorial
[$math:factorial] -> int — Return n factorial exactly: an int through 20!, a bigint past it; n may be a bigint; a negative n refuses CXER3003, a result wider than 2^20 bits CXER3000.
[?lib 'cx-stdlib/math']
[$math:factorial 0]
1
math:pow-mod
[$math:pow-mod] -> any — b to the e modulo m (Python's three-argument pow), exact over int and bigint without forming b^e; the result takes m's sign; a negative e is the modular inverse's power; m = 0 refuses CXER0101.
[?lib 'cx-stdlib/math']
[$math:pow-mod 2 10 1000]
24
math:pi
[$math:pi] -> float — Return the constant pi.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:tan [$math:round-to [$math:pi] 15]] 8]
0.0e0
math:e
[$math:e] -> float — Return Euler's number e.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:log [$math:e]] 8]
1.0e0
math:tau
[$math:tau] -> float — Return the constant tau (2 pi).
[?lib 'cx-stdlib/math']
[$math:round-to [/ [$math:tau] [$math:pi]] 8]
2.0e0
math:golden
[$math:golden] -> float — Return the golden ratio (1 + sqrt 5) / 2.
[?lib 'cx-stdlib/math']
[$math:round-to [$math:golden] 8]
1.61803399e0
math:infinity
[$math:infinity] -> float — Return positive IEEE 754 infinity.
[?lib 'cx-stdlib/math']
[$math:is-infinite [$math:infinity]]
true
math:nan
[$math:nan] -> float — Return an IEEE 754 NaN value.
[?lib 'cx-stdlib/math']
[$math:is-nan [$math:nan]]
true
math:epsilon
[$math:epsilon] -> float — Return the float64 machine epsilon.
[?lib 'cx-stdlib/math']
[$math:is-finite [$math:epsilon]]
true
math:wrapping-add
[$math:wrapping-add] -> int — Add two integers with two's-complement wraparound; never raises.
[?lib 'cx-stdlib/math']
[$math:wrapping-add 9223372036854775807 1]
-9223372036854775808
math:wrapping-sub
[$math:wrapping-sub] -> int — Subtract two integers with two's-complement wraparound; never raises.
[?lib 'cx-stdlib/math']
[$math:wrapping-sub -9223372036854775808 1]
9223372036854775807
math:wrapping-mul
[$math:wrapping-mul] -> int — Multiply two integers with two's-complement wraparound; never raises.
[?lib 'cx-stdlib/math']
[$math:wrapping-mul 6 7]
42
math:wrapping-pow
[$math:wrapping-pow] -> int — Raise base to exp with two's-complement wraparound; never raises.
[?lib 'cx-stdlib/math']
[$math:wrapping-pow 2 10]
1024
math:wrapping-shift-left
[$math:wrapping-shift-left] -> int — Two's-complement modular left shift over int64: the bits shifted past bit 63 are dropped; a count of 64 or more is 0; a negative count raises.
[?lib 'cx-stdlib/math']
[$math:wrapping-shift-left 1 63]
-9223372036854775808
math:isqrt
[$math:isqrt] -> any — The exact integer square root: the largest integer whose square is at most n (Python's math.isqrt), over int and bigint, computed in integer arithmetic — never through a float. An int while it fits int64, a bigint past it; a negative n refuses CXER3003, a float or decimal CXER0100.
[?lib 'cx-stdlib/math']
[$math:isqrt 17]
4
math:iroot
[$math:iroot] -> any — The exact integer k-th root: the largest integer r with r^k at most n, over int and bigint at any size, by isqrt's rule — never through a float. An int while it fits int64, a bigint past it; a negative n refuses CXER3003, a float or decimal n or a k that is not an int of at least 1 CXER0100.
[?lib 'cx-stdlib/math']
([$math:iroot 27 3], [$math:iroot 26 3], [= [$math:iroot [$pow 10 60] 3] [$pow 10 20]])
(3, 2, true)
math:floor-div
[$math:floor-div] -> any — Floored integer division: the quotient of a by b rounded toward negative infinity (Python's //), where div and idiv truncate toward zero. Exact over int and bigint — an int while it fits int64, a bigint past it; a float operand floors in floating point (a float), a decimal exactly (the integer floor); a zero divisor refuses CXER0101, a non-number CXER0100.
[?lib 'cx-stdlib/math']
([$math:floor-div -7 2], [$math:floor-div 7 -2], [$math:floor-div -9223372036854775808 -1], [$math:floor-div 123456789012345678901 -10])
(-4, -4, 9223372036854775808, -12345678901234567891)
math:floor-mod
[$math:floor-mod] -> any — Floored modulo: the remainder of a by b with the sign of the divisor b (Python's %), where % and mod take the dividend's sign; a equals b times floor-div plus floor-mod. Exact over int and bigint, and over a decimal (an exact decimal remainder); a float operand computes in floating point as Python's % does ([$math:floor-mod -9.0e1 360] is 2.7e2); a zero divisor refuses CXER0101, a non-number CXER0100.
[?lib 'cx-stdlib/math']
([$math:floor-mod -1 1440], [$math:floor-mod 7 -2], [$math:floor-mod -7 -2], [$math:floor-mod 123456789012345678901 -10])
(1439, -1, -1, -9)
math:div-decimal
[$math:div-decimal] -> any — Decimal division under an explicit rounding context: the exact quotient rounded to scale digits after the point ({scale: N mode: …}) or to precision significant digits ({precision: N mode: …}) per mode (:half-up | :half-even | :down | :up) — the only way to divide a non-terminating decimal quotient; the bare [/ …] operator stays exact-or-CXER3002.
[?lib 'cx-stdlib/math']
([$math:div-decimal 1.00 3.0 {scale: 4 mode: :half-up}], [$math:div-decimal 1.0 8.0 {scale: 2 mode: :half-even}], [$math:div-decimal -10.0 3.0 {scale: 2 mode: :down}])
(0.3333, 0.12, -3.33)