Math v0.1.0

Installation

Add Math to the [Dependencies] table of your package's Rux.toml:

[Dependencies]
Math = { Namespace = "Rux", Version = "0.1.0" }

Standard packages are declared by hand: the registry does not serve them, so rux add Rux/Math cannot add them.

Dependencies

• Core 0.1.0

Guide

Portable mathematical constants, elementary functions, floating-point utilities, and generic integer operations for Rux. The package implements its elementary functions directly instead of forwarding them to the host system's libm. Argument reduction, polynomial kernels, and IEEE 754 edge-case handling therefore remain consistent across supported targets. The implementation allocates no memory and depends only on Rux/Core.

Example

import Math::{ DegToRad, Hypot, SinCos };

let angle = DegToRad(30.0);
let (sine, cosine) = SinCos(angle);
let diagonal = Hypot(3.0, 4.0);

SinCos performs argument reduction once and returns (sine, cosine), which is more efficient than calling Sin and Cos separately for the same angle.

API overview

Most floating-point functions provide both float64 and float32 overloads. The float32 forms use a wide intermediate where doing so improves accuracy, then round once to the requested width.

Constants and angles

• Exponential and logarithmic — E, Ln2, Log2E, Ln10, and Log10E.
• Circular — Pi, Tau, HalfPi, QuarterPi, InvPi, and InvTau.
• Radicals — Sqrt2 and InvSqrt2.
• Angle conversion — RadPerDeg, DegPerRad, DegToRad, and RadToDeg.

All constants are float64 values rounded to the nearest representable value. See the constants reference for the complete list.

Elementary functions

Expm1(x) computes Exp(x) - 1, and Log1p(x) computes Log(1 + x), without discarding the small result near zero. PowInteger uses repeated squaring and preserves exact integer powers when the intermediate values are exactly representable; use Pow for a general floating-point exponent.

Rounding and conversion

• Floor, Ceil, Trunc, and Round provide the usual directed and ties-away rounding rules.
• RoundTiesToEven implements IEEE 754's default halfway rule.
• RoundTo selects a rule through RoundingMode.
• ToIntegerChecked<T> rounds and converts without silently saturating an out-of-range value.
• Mod computes the exact floating-point remainder with the sign of the dividend.

ToIntegerChecked<T> returns true on failure and writes zero to its output. The destination pointer must be non-null and writable:

import Math::{ RoundingMode, ToIntegerChecked };

var answer: int32 = 0;
let failed = ToIntegerChecked<int32>(42.5, 0, RoundingMode::ToNearestTiesEven, @answer);

Floating-point inspection and manipulation

ExponentOf reports NoExponent for zero and IndeterminateExponent for a NaN or infinity. UlpDistance counts representable steps rather than subtracting values, making it useful for numerical error checks across the full floating-point range.

Generic integer operations

The integer APIs are generic over signed and unsigned integer widths:

• AbsChecked<T> and AbsWrapping<T> compute a magnitude with explicit overflow behavior.
• Minimum<T>, Maximum<T>, and Clamp<T> provide scalar ordering operations.
• GcdChecked<T> and LcmChecked<T> implement number-theory operations.
• PowChecked<T> raises an integer to a non-negative integer power.

Checked operations follow the same convention as checked arithmetic in Rux/Core: they return true when the mathematical result is not representable. Their raw output pointers must be non-null, correctly aligned, and writable for one value for the duration of the call.

Complex numbers

Complex over float64 and Complex32 over float32 have +, -, * and /, Abs, Arg, Norm, Conjugate, Negate, Scale, FromPolar, and Exp, Log, Sqrt and Pow on the principal branch. Division uses Smith's method and the magnitude goes through Hypot, so neither overflows for parts far from one.

Numerical behavior

• IEEE 754 special values are part of each contract. Signed zeros, infinities, NaNs, subnormals, and domain errors are handled deliberately rather than left to host-library behavior.
• Accuracy is documented per function. The primary trigonometric, exponential, logarithmic, and root operations target an error of at most one ulp; inverse hyperbolic functions document a two-ulp bound.
• Large-angle reduction retains precision. Trigonometric functions reduce large finite inputs without first rounding them to a low-precision multiple of Pi / 2.
• No allocation or hidden global state. Every operation works on ordinary values and caller-provided outputs.

The bit-level implementation currently supports x86-64 and AArch64 targets.

Value and ownership model

The package owns no storage. FloatClass and RoundingMode are structural Copy values, and multi-result operations such as SinCos return tuples. Ordinary inputs are passed by value. Raw pointers appear only in checked operations and decomposition helpers that write an additional result supplied by the caller.

Index

Types

Functions

Constants