Docs/Standard library

math

Compute binary64 powers, roots, trigonometry, logarithms, rounding, and IEEE helpers.

Floating-point mathematics#

Import math for binary64 arithmetic implemented in Ocean and inline assembly, without C extern functions or libm. Mathematical arguments and results are float, including Pow(x float, y float) float, which accepts fractional exponents. Trigonometric angles use radians. Pi, E, Ln2, and Sqrt2 are exported float bindings; treat them as read-only by convention.

Ocean
package main;
import "math";
import "io";

func main() {
    root := math.Pow(9.0, 0.5);
    wave := math.Sin(math.Pi / 6.0);
    io.Println(root, " ", wave).unwrap();
}

Functions and bindings#

Unary mathematical functions accept one float; binary functions accept two floats. Classification returns bool. Float64bits converts float to uint, and Float64frombits converts uint to float without changing the bit pattern.

Functions and bindings reference
GroupExports
BindingsPi, E, Ln2, Sqrt2
TrigonometrySin, Cos, Tan, Asin, Acos, Atan, Atan2(y, x)
Powers and logarithmsPow(x, y), Exp, Exp2, Log, Log2, Log10, Sqrt, Hypot(x, y)
Rounding and arithmeticAbs, Copysign(x, y), Trunc, Floor, Ceil, Round, Min(x, y), Max(x, y), Mod(x, y)
IEEE helpersNaN() float, Inf(sign int) float, IsNaN(x float) bool, IsInf(x float, sign int) bool, Signbit(x float) bool, Float64bits(x float) uint, Float64frombits(bits uint) float

Rounding and special values#

Round rounds halfway cases away from zero. Mod uses a quotient truncated toward zero and preserves the dividend’s sign, including signed zero. Min and Max propagate NaN and choose negative and positive zero respectively. Copysign takes the magnitude of x and sign of y.

Inf returns negative infinity for a negative sign and positive infinity otherwise. IsInf accepts either infinity for sign zero, or the specified sign otherwise. Domain errors return NaN; Log(0) returns negative infinity. Overflow returns infinity, and underflow can produce subnormals or signed zero. Pow supports negative bases with integral exponents and special cases including Pow(NaN(), 0) and Pow(1, NaN()), both returning 1.

Accuracy and native paths#

These are approximate routines, without a guarantee of correct rounding. Trigonometric reduction uses binary64 2π, so error grows with magnitude and very large angles can lose meaningful phase information. Tan loses accuracy near its poles. Keep angles near a few revolutions when accuracy matters. The portable Pow fallback can amplify logarithm rounding for large exponents.

Integer powers use exponentiation by squaring. Fractional powers use x87 instructions on x86-64, with Ocean logarithm/exponential routines elsewhere. Sqrt uses native instructions on x86-64, AArch64, and RISC-V64, and normalized Newton iteration elsewhere. Native paths have been executed on x86-64; other hosts still need validation.

Run the tests#

Tests exercise powers, roots, logarithms, trigonometry, rounding, IEEE edge cases, and reference values.

Ocean
OCEAN_SRC=/path/to/ocean-src ocean test /path/to/ocean-src/math