Skip to main content

46  math standard library

The math module exposes C99 libm mathematical functions for 64-bit IEEE 754 Float values, along with angle conversion helpers. Importing math automatically links -lm.

Mathematical constants (const::pi, const::tau, const::e, const::phi, const::inv_phi, const::sqrt2, const::sqrt3, const::ln2, const::ln10) live in the const standard library module (#use const).

#use math

46.1 Function catalog

(Note: Operations covered by hardware/LLVM intrinsics — %sqrt, %pow, %exp2, %log2, %sin, %cos, %floor, %ceil, %trunc, %round, %abs, %min, %max, %clamp, %copysign, %fma, %fmuladd — are built into the language directly and also support SIMD vector tuples).

46.1.1 Angle conversions

Function Signature Description Example
math::rad(deg) Float => Float Converts degrees to radians (deg * const::pi / 180.0) math::rad(180.0) \(\rightarrow\) \(\pi\)
math::deg(rad) Float => Float Converts radians to degrees (rad * 180.0 / const::pi) math::deg(const::pi) \(\rightarrow\) 180.0

46.1.2 Roots and powers

Function Signature Description Example
math::cbrt(x) Float => Float Cube root \(\sqrt[3]{x}\) math::cbrt(27.0) \(\rightarrow\) 3.0
math::hypot(x, y) Float, Float => Float Hypotenuse \(\sqrt{x^2 + y^2}\) math::hypot(3.0, 4.0) \(\rightarrow\) 5.0

46.1.3 Exponentials and logarithms

Function Signature Description
math::exp(x) Float => Float Natural exponential \(e^x\)
math::expm1(x) Float => Float \(e^x - 1\) (accurate for small \(x\))
math::log(x) Float => Float Natural logarithm \(\ln(x)\)
math::log10(x) Float => Float Common logarithm \(\log_{10}(x)\)
math::log1p(x) Float => Float \(\ln(1 + x)\) (accurate for small \(x\))

46.1.4 Trigonometry and hyperbolics

Function Signature Description
math::tan(x) Float => Float Tangent (radians)
math::asin(x), math::acos(x), math::atan(x) Float => Float Inverse circular functions
math::atan2(y, x) Float, Float => Float Multi-quadrant inverse tangent
math::sinh(x), math::cosh(x), math::tanh(x) Float => Float Hyperbolic sine, cosine, tangent
math::asinh(x), math::acosh(x), math::atanh(x) Float => Float Inverse hyperbolic functions

46.1.5 Rounding and floating-point manipulation

Function Signature Description
math::rint(x) Float => Float Round to nearest integer using current rounding mode
math::nearbyint(x) Float => Float Round to nearest integer without raising FE_INEXACT
math::fmod(x, y) Float, Float => Float Floating-point remainder of \(x / y\)
math::remainder(x, y) Float, Float => Float IEEE 754 remainder of \(x / y\)
math::fdim(x, y) Float, Float => Float Positive difference \(\max(x - y, 0)\)
math::ldexp(x, exp) Float, i32 => Float \(x \times 2^{\text{exp}}\)
math::scalbn(x, n) Float, i32 => Float \(x \times \text{FLT\_RADIX}^n\)

46.2 Submodules

46.2.1 math/geom — 2D, 3D, and 4D Euclidean geometry

Import with #use math/geom. Operates on homogeneous named-field float tuples (Vec2, Vec3, Vec4, Point2, Point3, Rect), supporting .x/.y/.z/.w field access, v(0)..v(3) indexing, native SIMD arithmetic (+, -, *, /), and hardware vector intrinsics (%dot, %sqrt, %fmuladd).

Export Signature Description
Vec2 (x: Float, y: Float) 2D vector / coordinate tuple
Vec3 (x: Float, y: Float, z: Float) 3D vector tuple
Vec4 (x: Float, y: Float, z: Float, w: Float) 4D vector / homogeneous coordinate tuple
Point2 (x: Float, y: Float) 2D point alias
Point3 (x: Float, y: Float, z: Float) 3D point alias
Rect (x: Float, y: Float, w: Float, h: Float) 2D axis-aligned rectangle (x, y, w, h)
geom::vec2 Float, Float => Vec2 2D vector constructor
geom::vec3 Float, Float, Float => Vec3 3D vector constructor
geom::vec4 Float, Float, Float, Float => Vec4 4D vector constructor
geom::rect Float, Float, Float, Float => Rect Rectangle constructor
geom::rad Float => Float Converts degrees to radians (deg * const::pi / 180.0)
geom::deg Float => Float Converts radians to degrees (rad * 180.0 / const::pi)
geom::dot Vec2, Vec2 => Float 2D dot product via %dot
geom::len Vec2 => Float 2D vector Euclidean magnitude
geom::dist Vec2, Vec2 => Float 2D Euclidean distance between vectors
geom::dist_sq Vec2, Vec2 => Float Squared 2D Euclidean distance
geom::norm Vec2 => Vec2 Unit normalized 2D vector (returns (0.0, 0.0) if len < 1e-9)
geom::lerp Vec2, Vec2, Float => Vec2 Linear interpolation a + (b - a) * t via %fmuladd
geom::angle Vec2 => Float Direction angle in radians via atan2
geom::angle_deg Vec2 => Float Direction angle in degrees normalized to [0, 360)
geom::rotate Vec2, Float => Vec2 Rotates vector counterclockwise by angle in radians
geom::dot3 Vec3, Vec3 => Float 3D dot product
geom::len3 Vec3 => Float 3D vector Euclidean magnitude
geom::dist3 Vec3, Vec3 => Float 3D Euclidean distance
geom::norm3 Vec3 => Vec3 Unit normalized 3D vector
geom::cross3 Vec3, Vec3 => Vec3 3D vector cross product
geom::normal3 Vec3, Vec3, Vec3 => Vec3 Unit surface normal norm3(cross3(b - a, c - a))
geom::rect_contains Rect, Point2 => <> Tests whether point (px, py) lies inside rectangle
geom::circle_contains Point2, Float, Point2 => <> Tests whether point lies within circle (center, radius)
geom::rect_union Rect, Rect => Rect Bounding rectangle enclosing both rectangles
geom::rect_intersect Rect, Rect => Rect Overlapping region of two rectangles 
#use io
#use math/geom

v = geom::vec2(3.0, 4.0)
io::out(geom::len(v))
// => 5

46.2.2 math/complex — Complex numbers and FFT

Import with #use math/complex. Provides Cartesian and polar complex arithmetic and hardware-accelerated Cooley-Tukey Radix-2 FFT.

Export Signature Description
Complex (re: Float, im: Float) Complex number record with real and imaginary parts
complex::make Float, Float => Complex Constructs complex number re + im * i
complex::from_real Float => Complex Real scalar embed r + 0i
complex::zero! () => Complex Additive identity 0 + 0i
complex::one! () => Complex Multiplicative identity 1 + 0i
complex::i! () => Complex Imaginary unit 0 + 1i
complex::real Complex => Float Extracts real component .re
complex::imag Complex => Float Extracts imaginary component .im
complex::add Complex, Complex => Complex Complex addition (a + b)
complex::sub Complex, Complex => Complex Complex subtraction (a - b)
complex::mul Complex, Complex => Complex Complex multiplication via fused %fma
complex::scale Complex, Float => Complex Multiplies complex number by real scalar
complex::conj Complex => Complex Complex conjugate re - im * i
complex::norm_sq Complex => Float Squared magnitude re^2 + im^2
complex::abs Complex => Float Modulus / magnitude \(\sqrt{\text{re}^2 + \text{im}^2}\)
complex::arg Complex => Float Principal phase angle in radians \((-\pi, \pi]\)
complex::polar Float, Float => Complex Constructs from polar coordinates (r, theta)
complex::exp Complex => Complex Complex exponential \(e^z = e^{\text{re}}(\cos(\text{im}) + i\sin(\text{im}))\)
complex::fft ComplexArray => ComplexArray Cooley-Tukey Radix-2 forward FFT (\(N = 2^k\))
complex::ifft ComplexArray => ComplexArray Inverse FFT normalized by \(1/N\) 
#use io
#use math/complex

z1 = complex::make(1.0, 2.0)
z2 = complex::make(3.0, 4.0)
prod = complex::mul(z1, z2)
io::out((complex::real(prod), complex::imag(prod)))
// => -5 10