Lyricdev
GitHub

std.math

Provides the elementary functions and the mathematical constants.

The functions are free and generic over the numeric types: min, max, gcd, lcm, abs, signum, and for floating-point types rounding, roots, powers, logarithms and the trigonometric and hyperbolic functions. The constants pi, e and tau are typed float; math.pi as float32 gives the narrow width. What describes a number type itself stands at that type: float.epsilon, int.max, x.isNan().

The floating-point functions compute in float and round a float32 result once, at the end; they give the same bits on every tier-1 target.

Examples

import std.io { println };
import std.math;

println(math.sqrt(2.0));
println(math.hypot(3.0, 4.0));
println(math.gcd(84, 36));
println(math.max(7, 3));
1.4142135623730951
5.0
12
7

Types

Pow interface — A number to a power: an integer to a whole one, computed by squaring; a float to any.

Functions

pub fn min<T :: [Ordered]>(a: T, b: T): T

Returns the lesser of a and b.

Returns a when the two are equal, and when they are unordered (a NaN).

pub fn max<T :: [Ordered]>(a: T, b: T): T

Returns the greater of a and b.

Returns a when the two are equal, and when they are unordered (a NaN).

pub fn gcd<T :: [Integer]>(a: T, b: T): T

Returns the greatest common divisor of a and b, never negative.

gcd(0, 0) is 0.

Panics

When the divisor's magnitude does not fit the type: a signed type's min has none, so gcd(int.min, 0) overflows, as abs does.

pub fn lcm<T :: [Integer]>(a: T, b: T): T

Returns the least common multiple of a and b, never negative.

Returns 0 when either is 0.

Panics

When the multiple, or its magnitude, does not fit the type.

pub fn lerp<T :: [Float]>(a: T, b: T, t: T): T

Returns the value the fraction t of the way from a to b.

The result is exactly a at t = 0 and exactly b at t = 1; a t outside 0…1 extrapolates beyond the two.

pub fn floor<T :: [Float]>(x: T): T

Returns the greatest integral value not above x.

pub fn ceil<T :: [Float]>(x: T): T

Returns the least integral value not below x.

pub fn round<T :: [Float]>(x: T): T

Returns the integral value nearest to x, rounding halves away from zero.

pub fn trunc<T :: [Float]>(x: T): T

Returns the integral part of x, rounding toward zero.

pub fn sqrt<T :: [Float]>(x: T): T

Returns the square root of x; NaN below zero.

pub fn cbrt<T :: [Float]>(x: T): T

Returns the cube root of x.

pub fn exp<T :: [Float]>(x: T): T

Returns e to the power x.

pub fn ln<T :: [Float]>(x: T): T

Returns the natural logarithm of x; NaN below zero, negative infinity at zero.

pub fn log2<T :: [Float]>(x: T): T

Returns the logarithm of x to base 2.

pub fn log10<T :: [Float]>(x: T): T

Returns the logarithm of x to base 10.

pub fn sin<T :: [Float]>(x: T): T

Returns the sine of x, in radians.

pub fn cos<T :: [Float]>(x: T): T

Returns the cosine of x, in radians.

pub fn tan<T :: [Float]>(x: T): T

Returns the tangent of x, in radians.

pub fn asin<T :: [Float]>(x: T): T

Returns the arcsine of x, in radians.

pub fn acos<T :: [Float]>(x: T): T

Returns the arccosine of x, in radians.

pub fn atan<T :: [Float]>(x: T): T

Returns the arctangent of x, in radians.

pub fn sinh<T :: [Float]>(x: T): T

Returns the hyperbolic sine of x.

pub fn cosh<T :: [Float]>(x: T): T

Returns the hyperbolic cosine of x.

pub fn tanh<T :: [Float]>(x: T): T

Returns the hyperbolic tangent of x.

pub fn atan2<T :: [Float]>(y: T, x: T): T

Returns the angle of the point (x, y) from the positive x axis, in radians from -π to π.

pub fn hypot<T :: [Float]>(x: T, y: T): T

Returns the length of the hypotenuse of a right triangle with legs x and y.

Unlike sqrt(x * x + y * y), it does not overflow in the intermediate squares.

pub fn abs<T :: [Signed]>(x: T): T

Returns the magnitude of x, the value without its sign.

A float's -0.0 gives 0.0.

Panics

For a signed integer type's min, whose magnitude the type cannot hold.

pub fn signum<T :: [Signed]>(x: T): T

Returns the sign of x: -1, 0 or 1 as a value of its type.

A float's NaN gives NaN.

pub fn pow<T :: [Pow]>(x: T, e: T.Exponent): T

Returns x to the power e: pow(2, 10) is 1024, pow(2.0, 0.5) the square root of two.

pub fn checkedAdd<T :: [Integer]>(a: T, b: T): ?T

Returns the sum, or null where it does not fit the type.

pub fn checkedSub<T :: [Integer]>(a: T, b: T): ?T

Returns the difference, or null where it does not fit.

pub fn checkedMul<T :: [Integer]>(a: T, b: T): ?T

Returns the product, or null where it does not fit.

pub fn checkedDiv<T :: [Integer]>(a: T, b: T): ?T

Returns the quotient, or null for a zero divisor and for min / -1, which does not fit.

pub fn checkedRem<T :: [Integer]>(a: T, b: T): ?T

Returns the remainder, or null for a zero divisor; a remainder by -1 is 0.

pub fn saturatingAdd<T :: [Integer]>(a: T, b: T): T

Returns the sum, held at min or max where it does not fit.

pub fn saturatingSub<T :: [Integer]>(a: T, b: T): T

Returns the difference, held at min or max where it does not fit.

pub fn saturatingMul<T :: [Integer]>(a: T, b: T): T

Returns the product, held at min or max by the sign it would have.

pub fn wrappingAdd<T :: [Integer]>(a: T, b: T): T

Returns the sum modulo 2^bitWidth, as +% on the type.

pub fn wrappingSub<T :: [Integer]>(a: T, b: T): T

Returns the difference modulo 2^bitWidth, as -%.

pub fn wrappingMul<T :: [Integer]>(a: T, b: T): T

Returns the product modulo 2^bitWidth, as *%.

pub fn wrappingDiv<T :: [Integer]>(a: T, b: T): T

Returns the quotient, where min / -1 wraps to min.

Panics

When b is zero, as / does.

pub fn wrappingRem<T :: [Integer]>(a: T, b: T): T

Returns the remainder, where a remainder by -1 is 0.

Panics

When b is zero, as % does.

pub fn leadingZeros<T :: [Integer]>(x: T): int

Returns the number of zero bits above the highest one bit; bitWidth for zero.

pub fn trailingZeros<T :: [Integer]>(x: T): int

Returns the number of zero bits below the lowest one bit; bitWidth for zero.

pub fn popCount<T :: [Integer]>(x: T): int

Returns the number of one bits.

pub fn rotateLeft<T :: [Integer]>(x: T, n: int): T

Returns the bits rotated left by n, modulo bitWidth; a negative n rotates right.

pub fn rotateRight<T :: [Integer]>(x: T, n: int): T

Returns the bits rotated right by n, modulo bitWidth; a negative n rotates left.

pub fn clamp<T :: [Ordered]>(x: T, lo: T, hi: T): T

Returns x held to lo…hi: lo below it, hi above it.

A value unordered with the bounds, such as a NaN, comes back as it is.

Panics

When lo is above hi.

Constants

pub let pi: float = 3.141592653589793

π, a half turn in radians.

pub let e: float = 2.718281828459045

e, the base of the natural logarithm.

pub let tau: float = 6.283185307179586

τ = 2π, a full turn in radians.

Extensions

extend int :: [Pow]

Conforms to Pow.

fn pow(n: uint): int
extend int8 :: [Pow]

Conforms to Pow.

fn pow(n: uint): int8
extend int16 :: [Pow]

Conforms to Pow.

fn pow(n: uint): int16
extend int32 :: [Pow]

Conforms to Pow.

fn pow(n: uint): int32
extend uint :: [Pow]

Conforms to Pow.

fn pow(n: uint): uint
extend uint8 :: [Pow]

Conforms to Pow.

fn pow(n: uint): uint8
extend uint16 :: [Pow]

Conforms to Pow.

fn pow(n: uint): uint16
extend uint32 :: [Pow]

Conforms to Pow.

fn pow(n: uint): uint32
extend float :: [Pow]

Conforms to Pow.

fn pow(e: float): float
extend float32 :: [Pow]

Conforms to Pow.

fn pow(e: float32): float32