std/numeric/math
std/numeric/math — numeric utilities.
Pure functions over scalar primitives. No state, no allocation,
no exceptions: every operation that would mathematically fail
(sqrt of a negative, log of zero, …) follows IEEE 754 semantics
and returns NaN / ±∞ rather than throwing.
Constants and operations that DO have a natural receiver (x.sqrt(),n.abs(), a.min(b), x.ln(), …) resolve through the primitive
method surface (axle_hir::primitive_methods) to the __-prefixed
free functions below — there is no Math class here. What has no
single natural receiver (pi, atan2(y, x), the type bounds) stays a
plain module-level free function, reached as math::pi() /math::atan2(y, x) after use std::numeric::math;.
Free functions
| Type | Method and description |
|---|---|
| __f64Sqrt(x : f64) : f64 x.sqrt() — NaN for a negative x, +inf for +inf. |
| __f64Pow(base : f64, exponent : f64) : f64 x.pow(e) — pow(x, 0.0) is 1.0 for every x, NaN included. |
| __f64Floor(x : f64) : f64 x.floor() — the largest integral value not above x. |
| __f64Ceil(x : f64) : f64 x.ceil() — the smallest integral value not below x. |
| __f64Trunc(x : f64) : f64 x.trunc() — the integral part of x, toward zero. |
| __f64Round(x : f64) : i64 x.round() — half away from zero, narrowed to i64.The boundary as i64 lowers through the saturating fptosi.satintrinsic, so an out-of-range magnitude clamps and NaN maps to 0instead of being undefined. |
| __f64Abs(x : f64) : f64 x.abs() — magnitude, NaN passed through unchanged.Delegates rather than branching on the sign: -0.0 < 0.0 is false, so acomparison returns -0.0 where IEEE-754 requires +0.0. Equality hidesthe difference ( -0.0 == 0.0), so the wrong sign leaks out silentlythrough toString, reciprocals, copysign and atan2. libm::fabslowers to @llvm.fabs.f64 — correct on every zero, and one instruction. |
| __f64Min(a : f64, b : f64) : f64 a.min(b) — the smaller, and b when either is NaN.The NaN answer is the comparison's, not a choice made here: a < b isfalse whenever a NaN is involved, so the fallthrough returns b. Statedbecause the two orders are not interchangeable for a caller who cares. |
| __f64Max(a : f64, b : f64) : f64 a.max(b) — the larger, and b when either is NaN. |
| __i32Abs(x : i32) : i32 n.abs() — wraps on i32::MIN, whose negation does not fit in i32.The checked form that reports the case instead is n.absChecked(). |
| __i32Min(a : i32, b : i32) : i32 a.min(b). |
| __i32Max(a : i32, b : i32) : i32 a.max(b). |
| __i32AbsChecked(x : i32) : i32 n.absChecked() — throws on i32::MIN, where -x would overflow.i32::MIN = -(i32::MAX) - 1, where i32::MAX = 0x7FFFFFFF. |
| __i64Abs(x : i64) : i64 n.abs() — wraps on i64::MIN, like its i32 twin. |
| __i64Min(a : i64, b : i64) : i64 a.min(b). |
| __i64Max(a : i64, b : i64) : i64 a.max(b). |
| __i64AbsChecked(x : i64) : i64 n.absChecked() — throws on i64::MIN, where -x would overflow.Built as -(i64::MAX) - 1 to avoid an out-of-range positive literal( 0x8000000000000000 exceeds i64::MAX). |
| __f64Cbrt(x : f64) : f64 x.cbrt() — real cube root, defined for every real, negatives included. |
| __f64Exp(x : f64) : f64 x.exp() — e raised to the power x. |
| __f64Ln(x : f64) : f64 x.ln() — natural logarithm; NaN below zero, -∞ at zero. |
| __f64Log2(x : f64) : f64 x.log2() — base-2 logarithm; NaN below zero, -∞ at zero. |
| __f64Log10(x : f64) : f64 x.log10() — base-10 logarithm; NaN below zero, -∞ at zero. |
| __f64Sin(x : f64) : f64 x.sin() — x in radians. |
| __f64Cos(x : f64) : f64 x.cos() — x in radians. |
| __f64Tan(x : f64) : f64 x.tan() — x in radians. |
| __f64Asin(x : f64) : f64 x.asin() — principal value in [-pi/2, pi/2]; NaN outside [-1, 1]. |
| __f64Acos(x : f64) : f64 x.acos() — principal value in [0, pi]; NaN outside [-1, 1]. |
| __f64Atan(x : f64) : f64 x.atan() — principal value in [-pi/2, pi/2]. |
| __f64Sinh(x : f64) : f64 x.sinh() — hyperbolic sine. |
| __f64Cosh(x : f64) : f64 x.cosh() — hyperbolic cosine. |
| __f64Tanh(x : f64) : f64 x.tanh() — hyperbolic tangent, range (-1, 1). |
| __f64Sign(x : f64) : f64 x.sign() — -1.0, 0.0, or 1.0; sign(0.0) is 0.0. sign(NaN)is NaN, read off isNaN directly rather than a self-compare, for thesame FpMode::Fast reason __f64IsNaN reads the bit pattern. |
| __f64TruncToInt(x : f64) : i64 x.truncToInt() — truncates toward zero. as i64 (fptosi, saturating)already rounds toward zero and clamps NaN/±inf/out-of-range, so a preceding libm::trunc call would be pure overhead: the cast alone isexact and branch-free. |
| __f64FloorToInt(x : f64) : i64 x.floorToInt() — floors toward -∞; out-of-range clamps, NaN → 0. |
| __f64CeilToInt(x : f64) : i64 x.ceilToInt() — ceils toward +∞; out-of-range clamps, NaN → 0. |
| pi() : f64 π — ratio of a circle's circumference to its diameter. |
| e() : f64 e — base of the natural logarithm (Euler's number). |
| tau() : f64 τ — one full turn in radians (2·π). |
| atan2(y : f64, x : f64) : f64 Arctangent of y / x, using the signs of both arguments to select thecorrect quadrant; result in (-pi, pi] radians. Two arguments with nosingle preferred subject, so this stays a free function rather than a method on either. |
| hypot(x : f64, y : f64) : f64 Euclidean distance sqrt(x*x + y*y), computed without intermediateoverflow or underflow. Symmetric in its two arguments, so no receiver reads more naturally than the other. |
| sinCos(x : f64) : (f64, f64) Combined sin + cos of the same argument. The GNU sincos extensionwould fuse the two through one shared argument reduction (~33% on glibc / musl), but it isn't part of the MSVC / lld libm, so a portable wrapper that issues both calls keeps the surface usable everywhere. |
| absF32(x : f32) : f32 Absolute value of an f32. absF32(-0.0) is 0.0; NaN is returnedunchanged. Widens and delegates rather than branching on the sign, for the reason [ __f64Abs] states: -0.0 < 0.0 is false, so a comparison returns -0.0where IEEE-754 requires +0.0, and -0.0 == 0.0 hides it until the signleaks out through toString, a reciprocal, copysign or atan2. Bothconversions are exact — every f32 is an f64, and the magnitude of anf32 is an f32 — so the round trip changes nothing but the sign bit.f32 is not part of the primitive-receiver gate( hir_builder::…::calls::method), so — unlike f64.abs() — this stays afree function rather than a method; admitting f32 there is a receiver-gate decision, not a stdlib one. |
| i32Min() : i32 Smallest representable i32 (i32::MIN). |
| i32Max() : i32 Largest representable i32 (i32::MAX). |
| i64Min() : i64 Smallest representable i64 (i64::MIN). |
| i64Max() : i64 Largest representable i64 (i64::MAX). |
| f64Min() : f64 Smallest positive normal f64. |
| f64Max() : f64 Largest finite f64. |
| f64PositiveInfinity() : f64 +∞. |
| f64NegativeInfinity() : f64 -∞. Its pattern 0xFFF0000000000000 sets the sign bit, so it can't bean i64 hex literal directly — the two's complement of0x0010000000000000 is exactly that pattern. |
| f64NotANumber() : f64 A quiet NaN. |
Method detail
#__f64Sqrt
x.sqrt() — NaN for a negative x, +inf for +inf.
#__f64Pow
x.pow(e) — pow(x, 0.0) is 1.0 for every x, NaN included.
#__f64Floor
x.floor() — the largest integral value not above x.
#__f64Ceil
x.ceil() — the smallest integral value not below x.
#__f64Trunc
x.trunc() — the integral part of x, toward zero.
#__f64Round
x.round() — half away from zero, narrowed to i64.
The boundary as i64 lowers through the saturating fptosi.sat
intrinsic, so an out-of-range magnitude clamps and NaN maps to 0
instead of being undefined.
#__f64Abs
x.abs() — magnitude, NaN passed through unchanged.
Delegates rather than branching on the sign: -0.0 < 0.0 is false, so a
comparison returns -0.0 where IEEE-754 requires +0.0. Equality hides
the difference (-0.0 == 0.0), so the wrong sign leaks out silently
through toString, reciprocals, copysign and atan2. libm::fabs
lowers to @llvm.fabs.f64 — correct on every zero, and one instruction.
#__f64Min
a.min(b) — the smaller, and b when either is NaN.
The NaN answer is the comparison's, not a choice made here: a < b is
false whenever a NaN is involved, so the fallthrough returns b. Stated
because the two orders are not interchangeable for a caller who cares.
#__f64Max
a.max(b) — the larger, and b when either is NaN.
#__i32Abs
n.abs() — wraps on i32::MIN, whose negation does not fit in i32.
The checked form that reports the case instead is n.absChecked().
#__i32Min
a.min(b).
#__i32Max
a.max(b).
#__i32AbsChecked
n.absChecked() — throws on i32::MIN, where -x would overflow.i32::MIN = -(i32::MAX) - 1, where i32::MAX = 0x7FFFFFFF.
#__i64Abs
n.abs() — wraps on i64::MIN, like its i32 twin.
#__i64Min
a.min(b).
#__i64Max
a.max(b).
#__i64AbsChecked
n.absChecked() — throws on i64::MIN, where -x would overflow.
Built as -(i64::MAX) - 1 to avoid an out-of-range positive literal
(0x8000000000000000 exceeds i64::MAX).
#__f64Cbrt
x.cbrt() — real cube root, defined for every real, negatives included.
#__f64Exp
x.exp() — e raised to the power x.
#__f64Ln
x.ln() — natural logarithm; NaN below zero, -∞ at zero.
#__f64Log2
x.log2() — base-2 logarithm; NaN below zero, -∞ at zero.
#__f64Log10
x.log10() — base-10 logarithm; NaN below zero, -∞ at zero.
#__f64Sin
x.sin() — x in radians.
#__f64Cos
x.cos() — x in radians.
#__f64Tan
x.tan() — x in radians.
#__f64Asin
x.asin() — principal value in [-pi/2, pi/2]; NaN outside [-1, 1].
#__f64Acos
x.acos() — principal value in [0, pi]; NaN outside [-1, 1].
#__f64Atan
x.atan() — principal value in [-pi/2, pi/2].
#__f64Sinh
x.sinh() — hyperbolic sine.
#__f64Cosh
x.cosh() — hyperbolic cosine.
#__f64Tanh
x.tanh() — hyperbolic tangent, range (-1, 1).
#__f64Sign
x.sign() — -1.0, 0.0, or 1.0; sign(0.0) is 0.0. sign(NaN)
is NaN, read off isNaN directly rather than a self-compare, for the
same FpMode::Fast reason __f64IsNaN reads the bit pattern.
#__f64TruncToInt
x.truncToInt() — truncates toward zero. as i64 (fptosi, saturating)
already rounds toward zero and clamps NaN/±inf/out-of-range, so a
preceding libm::trunc call would be pure overhead: the cast alone is
exact and branch-free.
#__f64FloorToInt
x.floorToInt() — floors toward -∞; out-of-range clamps, NaN → 0.
#__f64CeilToInt
x.ceilToInt() — ceils toward +∞; out-of-range clamps, NaN → 0.
#pi
π — ratio of a circle's circumference to its diameter.
#e
e — base of the natural logarithm (Euler's number).
#tau
τ — one full turn in radians (2·π).
#atan2
Arctangent of y / x, using the signs of both arguments to select the
correct quadrant; result in (-pi, pi] radians. Two arguments with no
single preferred subject, so this stays a free function rather than a
method on either.
y ordinate (numerator)x abscissa (denominator)#hypot
Euclidean distance sqrt(x*x + y*y), computed without intermediate
overflow or underflow. Symmetric in its two arguments, so no receiver
reads more naturally than the other.
x first leg of the right triangley second leg of the right triangle#sinCos
Combined sin + cos of the same argument. The GNU sincos extension
would fuse the two through one shared argument reduction (~33% on glibc /
musl), but it isn't part of the MSVC / lld libm, so a portable wrapper
that issues both calls keeps the surface usable everywhere.
x angle in radians#absF32
Absolute value of an f32. absF32(-0.0) is 0.0; NaN is returned
unchanged.
Widens and delegates rather than branching on the sign, for the reason
[__f64Abs] states: -0.0 < 0.0 is false, so a comparison returns -0.0
where IEEE-754 requires +0.0, and -0.0 == 0.0 hides it until the sign
leaks out through toString, a reciprocal, copysign or atan2. Both
conversions are exact — every f32 is an f64, and the magnitude of anf32 is an f32 — so the round trip changes nothing but the sign bit.f32 is not part of the primitive-receiver gate
(hir_builder::…::calls::method), so — unlike f64.abs() — this stays a
free function rather than a method; admitting f32 there is a receiver-
gate decision, not a stdlib one.
x value whose magnitude is taken#i32Min
Smallest representable i32 (i32::MIN).
#i32Max
Largest representable i32 (i32::MAX).
#i64Min
Smallest representable i64 (i64::MIN).
#i64Max
Largest representable i64 (i64::MAX).
#f64Min
Smallest positive normal f64.
#f64Max
Largest finite f64.
#f64PositiveInfinity
+∞.
#f64NegativeInfinity
-∞. Its pattern 0xFFF0000000000000 sets the sign bit, so it can't be
an i64 hex literal directly — the two's complement of0x0010000000000000 is exactly that pattern.
#f64NotANumber
A quiet NaN.