silk.num.f32.

When to use#

Use f32 when binary32 storage, interchange, or bandwidth is part of the contract. Use f64 for general floating-point work and unconstrained literals. It preserves substantially more precision and is Silk's default floating type.

Details#

Basic arithmetic rounds to nearest with ties to even and never enables implicit fast-math assumptions. Division by zero and overflow produce IEEE infinities or NaNs rather than integer- style traps. Ordinary ordered comparisons return false for NaN and treat both zeros as equal; totalOrder distinguishes every encoding when deterministic ordering is required. The Order conformance of f32 uses the same total order, so List<f32>.sort puts negative NaNs first, then -0.0 before +0.0, and positive NaNs last.

toBits and fromBits expose the exact binary32 representation, including signed zero and NaN payloads. The source-defined rounding, extrema, sign, and square-root helpers canonicalize NaN results so native and WebAssembly execution agree on their bits.

The trigonometric, inverse trigonometric, exponential, logarithmic, power, cube root, hypot, and fma functions never call a host math library. Each states its error bound in units in the last place, returns the same bits on every target, WebAssembly included, and gives the canonical quiet NaN for every NaN result.

Gotchas#

Converting to an integer discards the fractional part and traps for NaN, infinity, or a value outside the destination range. The checkedTo* counterparts return None on exactly those inputs instead of trapping. Converting a large integer to f32 can round it.

Examples#

Inspect a binary32 boundary by its bits#

import silk.num.f32

pub fn main() -> i32 {
  let rounded = f32.round(-0.25)
  if f32.toBits(rounded) != f32.toBits(-0.0) {
    return 1
  }
  if !f32.isNaN(f32.sqrt(-1.0)) {
    return 1
  }
  return 0
}

Import as f32 with import silk.num.f32.

Public declarations: 72.

MAX#

pub const MAX: f32

The largest finite f32 value.

MIN#

pub const MIN: f32

The most negative finite f32 value, which is the negation of MAX.

EPSILON#

pub const EPSILON: f32

The distance from 1.0 to the next larger f32 value.

INFINITY#

pub const INFINITY: f32

Positive infinity with the binary32 bit pattern 0x7F800000.

Details#

No source literal spells infinity, and a literal that rounds to infinity is rejected. Doubling MAX overflows to the infinity encoding.

NAN#

pub const NAN: f32

The canonical quiet NaN, with the binary32 bit pattern 0x7FC00000.

Details#

No source literal spells NaN. Infinity minus infinity is NaN, and static evaluation always produces the canonical quiet NaN for a NaN result.

Gotchas#

NaN compares unequal to every value, itself included. Test for it with isNaN.

PI#

pub const PI: f32

The ratio of a circle's circumference to its diameter, rounded to the nearest f32 value.

E#

pub const E: f32

Euler's number, rounded to the nearest f32 value.

negate#

pub fn negate(value: f32) -> f32

Returns value with its sign reversed.

add#

pub fn add(left: f32, right: f32) -> f32

Returns left + right, rounded to nearest with ties to even. Overflow produces infinity. It does not trap.

subtract#

pub fn subtract(left: f32, right: f32) -> f32

Returns left - right, rounded to nearest with ties to even. Overflow produces infinity. It does not trap.

multiply#

pub fn multiply(left: f32, right: f32) -> f32

Returns left * right, rounded to nearest with ties to even. Overflow produces infinity. It does not trap.

divide#

pub fn divide(left: f32, right: f32) -> f32

Returns left / right, rounded to nearest with ties to even. Division by zero produces infinity or NaN. It does not trap.

remainder#

pub fn remainder(left: f32, right: f32) -> f32

Returns left - trunc(left / right) * right. A zero right, infinite left, or NaN operand produces NaN. It does not trap.

equals#

pub fn equals(left: f32, right: f32) -> bool

Returns true when both values compare equal. Returns false if either value is NaN.

notEquals#

pub fn notEquals(left: f32, right: f32) -> bool

Returns true when values do not compare equal, including when either value is NaN.

lessThan#

pub fn lessThan(left: f32, right: f32) -> bool

Returns true when left is less than right. Returns false if either value is NaN.

lessOrEqual#

pub fn lessOrEqual(left: f32, right: f32) -> bool

Returns true when left is less than or equal to right. Returns false for NaN.

greaterThan#

pub fn greaterThan(left: f32, right: f32) -> bool

Returns true when left is greater than right. Returns false if either value is NaN.

greaterOrEqual#

pub fn greaterOrEqual(left: f32, right: f32) -> bool

Returns true when left is greater than or equal to right. Returns false for NaN.

isNaN#

pub fn isNaN(value: f32) -> bool

Returns true when value is a NaN.

isInfinite#

pub fn isInfinite(value: f32) -> bool

Returns true when value is positive or negative infinity.

isFinite#

pub fn isFinite(value: f32) -> bool

Returns true when value is neither infinity nor NaN.

isNormal#

pub fn isNormal(value: f32) -> bool

Returns true when value is finite, nonzero, and not subnormal.

isSubnormal#

pub fn isSubnormal(value: f32) -> bool

Returns true when value is finite and has subnormal magnitude.

isSignNegative#

pub fn isSignNegative(value: f32) -> bool

Returns true when the sign bit of value is set, including for zero and NaN.

totalOrder#

pub fn totalOrder(left: f32, right: f32) -> bool

Reports whether left precedes or equals right in the IEEE total order.

When to use#

Use this function for deterministic ordering that includes NaNs and distinguishes signed zero.

Details#

Unlike ordinary comparison, this order distinguishes negative and positive zero and provides a deterministic position for NaN encodings.

The order is: negative NaNs, negative infinity, the negative numbers, -0.0, +0.0, the positive numbers, positive infinity, then positive NaNs. The Order conformance of f32, which sorting and binary search use, follows it.

toBits#

pub fn toBits(value: f32) -> u32

Reinterprets a value as its exact 32-bit IEEE representation.

When to use#

Use this function to inspect or preserve representation bits. It does not convert the number.

fromBits#

pub fn fromBits(value: u32) -> f32

Reinterprets an arbitrary 32-bit pattern as f32 without numeric conversion.

When to use#

Use this function to construct a value from representation bits, including NaN and signed zero.

sqrt#

pub fn sqrt(value: f32) -> f32

Computes the correctly rounded square root and preserves either signed zero.

Details#

IEEE requires square root to be correctly rounded, so its native and WebAssembly instructions have one admissible numeric result.

Gotchas#

NaN and negative nonzero inputs return the canonical quiet NaN. Negative zero is not treated as negative and returns unchanged.

abs#

pub fn abs(value: f32) -> f32

Returns the magnitude of value, which clears the sign bit. A NaN input gives the canonical NaN.

copysign#

pub fn copysign(magnitude: f32, sign: f32) -> f32

Returns the magnitude of magnitude with the sign bit of sign. A NaN magnitude gives the canonical NaN rather than a signed NaN.

trunc#

pub fn trunc(value: f32) -> f32

Rounds toward zero while preserving the sign of a zero result.

Details#

A value in (-1.0, -0.0] becomes negative zero. A NaN becomes the canonical quiet NaN, while either infinity is already integral and returns unchanged.

floor#

pub fn floor(value: f32) -> f32

Returns the largest integral f32 that is not greater than value. A NaN input gives the canonical NaN.

ceil#

pub fn ceil(value: f32) -> f32

Returns the smallest integral f32 that is not less than value. A NaN input gives the canonical NaN.

round#

pub fn round(value: f32) -> f32

Rounds to the nearest integral f32, with a half rounded away from zero.

Details#

This differs from the ties-to-even policy used by basic arithmetic. A zero result keeps its input sign, and a NaN becomes the canonical quiet NaN.

min#

pub fn min(left: f32, right: f32) -> f32

Returns the lesser value and orders negative zero below positive zero. If an operand is NaN, returns the canonical NaN.

max#

pub fn max(left: f32, right: f32) -> f32

Returns the greater value and orders positive zero above negative zero. If an operand is NaN, returns the canonical NaN.

sin#

pub fn sin(value: f32) -> f32

Approximates sine within four units in the last place using deterministic result bits.

Details#

NaN and either infinity return the canonical quiet NaN. Either signed zero returns unchanged.

cos#

pub fn cos(value: f32) -> f32

Approximates cosine within four units in the last place using deterministic result bits.

Details#

NaN and either infinity return the canonical quiet NaN. Either signed zero returns positive one.

tan#

pub fn tan(value: f32) -> f32

Approximates tangent within one unit in the last place using deterministic result bits.

Details#

The tangent is computed in binary64 and rounded once to binary32, so the result stays accurate for every finite input, including the largest. NaN and either infinity return the canonical quiet NaN. Either signed zero returns unchanged.

atan#

pub fn atan(value: f32) -> f32

Approximates arctangent within one unit in the last place using deterministic result bits.

Details#

The result is in [-pi/2, pi/2]. NaN returns the canonical quiet NaN, either signed zero returns unchanged, and an infinity returns pi/2 with its sign.

atan2#

pub fn atan2(y: f32, x: f32) -> f32

Approximates the angle of the point (x, y) from the positive x axis within one unit in the last place using deterministic result bits.

When to use#

Use this function instead of atan(y / x) to get the angle of a vector in every quadrant, including when x is zero.

Details#

The result is in [-pi, pi] and takes the sign of y, including a signed zero y. A zero y returns itself when x is positive or +0.0, and pi with the sign of y when x is negative or -0.0. A zero x with nonzero y gives pi/2 with the sign of y. Two infinities give an odd multiple of pi/4. A NaN in either operand returns the canonical quiet NaN.

asin#

pub fn asin(value: f32) -> f32

Approximates arcsine within one unit in the last place using deterministic result bits.

Details#

The result is in [-pi/2, pi/2]. Either signed zero returns unchanged. NaN and any argument outside [-1, 1] return the canonical quiet NaN.

acos#

pub fn acos(value: f32) -> f32

Approximates arccosine within one unit in the last place using deterministic result bits.

Details#

The result is in [0, pi]. One returns positive zero. NaN and any argument outside [-1, 1] return the canonical quiet NaN.

exp#

pub fn exp(value: f32) -> f32

Approximates e raised to value within one unit in the last place using deterministic result bits.

Details#

A result too large for f32 is positive infinity, and one too small is positive zero. Negative infinity returns positive zero, positive infinity returns itself, and NaN returns the canonical quiet NaN. Either signed zero returns one.

log#

pub fn log(value: f32) -> f32

Approximates the natural logarithm within one unit in the last place using deterministic result bits.

Details#

Either signed zero returns negative infinity, and one returns positive zero. Positive infinity returns itself. NaN and any negative argument return the canonical quiet NaN.

pow#

pub fn pow(base: f32, exponent: f32) -> f32

Approximates base raised to exponent within one unit in the last place using deterministic result bits.

Details#

A negative base has a real power only for an integer exponent, and an odd integer gives a negative result. A result too large for f32 is an infinity, and one too small is a zero, each with that sign.

Gotchas#

The special cases follow IEEE-754 pow:

• A zero exponent returns one for every base, NaN included, and a base of one returns one for every exponent, NaN included.

• A base of negative one with an infinite exponent returns one.

• A zero base with a negative exponent returns an infinity, negative only for -0.0 with an odd integer exponent. With a positive exponent it returns a zero signed the same way.

• With an infinite exponent, a base whose magnitude is below one gives positive zero for positive infinity and positive infinity for negative infinity. A magnitude above one gives the reverse.

• A negative finite base with a finite non-integer exponent, and any other NaN operand, returns the canonical quiet NaN.

cbrt#

pub fn cbrt(value: f32) -> f32

Approximates the real cube root within one unit in the last place using deterministic result bits.

Details#

The result has the sign of value, so a negative argument has a negative root. Either signed zero and either infinity return unchanged. NaN returns the canonical quiet NaN.

hypot#

pub fn hypot(x: f32, y: f32) -> f32

Approximates sqrt(x * x + y * y) within one unit in the last place using deterministic result bits, without intermediate overflow or underflow.

When to use#

Use this function for the length of a vector or the distance between two points. It stays accurate where squaring an operand would overflow to infinity or underflow to zero.

Details#

The result is never negative, and the signs of the operands do not matter. An infinite operand returns positive infinity even when the other is NaN. Otherwise a NaN operand returns the canonical quiet NaN.

fma#

pub fn fma(left: f32, right: f32, addend: f32) -> f32

Computes left * right + addend with a single rounding, as the IEEE-754 fused multiply-add.

When to use#

Use this function for exact dot products, polynomial evaluation, and error terms, where rounding the product separately loses the low half that the addend should cancel.

Details#

The result is correctly rounded on every target, so it has one admissible value. Targets with a fused multiply-add instruction, AArch64 and x86-64 with the fma CPU feature, compute it with that instruction. Other targets, WebAssembly included, compute it with binary64 arithmetic.

Gotchas#

A NaN operand, or an infinite product with a zero operand or an infinite addend of the other sign, returns the canonical quiet NaN.

toF32#

pub fn toF32(value: f32) -> f32

Returns the same binary32 value unchanged.

toF64#

pub fn toF64(value: f32) -> f64

Converts binary32 to the exactly equivalent f64 value.

toU8#

pub fn toU8(value: f32) -> u8

Converts value toward zero to u8. Traps for NaN, infinity, or a result outside the u8 range.

checkedToU8#

pub fn checkedToU8(value: f32) -> Option<u8>

Converts value toward zero to u8, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toU8 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least zero and below 2^8. Both bounds are powers of two and so are exact in binary32. A bound converted from u8.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toU16#

pub fn toU16(value: f32) -> u16

Converts value toward zero to u16. Traps for NaN, infinity, or a result outside the u16 range.

checkedToU16#

pub fn checkedToU16(value: f32) -> Option<u16>

Converts value toward zero to u16, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toU16 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least zero and below 2^16. Both bounds are powers of two and so are exact in binary32. A bound converted from u16.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toU32#

pub fn toU32(value: f32) -> u32

Converts value toward zero to u32. Traps for NaN, infinity, or a result outside the u32 range.

checkedToU32#

pub fn checkedToU32(value: f32) -> Option<u32>

Converts value toward zero to u32, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toU32 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least zero and below 2^32. Both bounds are powers of two and so are exact in binary32. A bound converted from u32.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toU64#

pub fn toU64(value: f32) -> u64

Converts value toward zero to u64. Traps for NaN, infinity, or a result outside the u64 range.

checkedToU64#

pub fn checkedToU64(value: f32) -> Option<u64>

Converts value toward zero to u64, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toU64 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least zero and below 2^64. Both bounds are powers of two and so are exact in binary32. A bound converted from u64.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toUsize#

pub fn toUsize(value: f32) -> usize

Converts value toward zero to usize. Traps for NaN, infinity, or a result outside the usize range.

checkedToUsize#

pub fn checkedToUsize(value: f32) -> Option<usize>

Converts value toward zero to usize, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toUsize traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. usize follows the selected target's pointer width, so the bounds follow it too. The truncated value is accepted when it is at least zero and below 2^32 on a 32-bit target or 2^64 on a 64-bit one.

Every bound is a power of two and so is exact in binary32. A bound converted from usize.MAX would round outward and wrongly admit an overflowing value, and a bound fixed at 64-bit width would admit values that trap on a 32-bit target.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toI8#

pub fn toI8(value: f32) -> i8

Converts value toward zero to i8. Traps for NaN, infinity, or a result outside the i8 range.

checkedToI8#

pub fn checkedToI8(value: f32) -> Option<i8>

Converts value toward zero to i8, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toI8 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least -2^7 and below 2^7. Both bounds are powers of two and so are exact in binary32. A bound converted from i8.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toI16#

pub fn toI16(value: f32) -> i16

Converts value toward zero to i16. Traps for NaN, infinity, or a result outside the i16 range.

checkedToI16#

pub fn checkedToI16(value: f32) -> Option<i16>

Converts value toward zero to i16, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toI16 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least -2^15 and below 2^15. Both bounds are powers of two and so are exact in binary32. A bound converted from i16.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toI32#

pub fn toI32(value: f32) -> i32

Converts value toward zero to i32. Traps for NaN, infinity, or a result outside the i32 range.

checkedToI32#

pub fn checkedToI32(value: f32) -> Option<i32>

Converts value toward zero to i32, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toI32 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least -2^31 and below 2^31. Both bounds are powers of two and so are exact in binary32. A bound converted from i32.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toI64#

pub fn toI64(value: f32) -> i64

Converts value toward zero to i64. Traps for NaN, infinity, or a result outside the i64 range.

checkedToI64#

pub fn checkedToI64(value: f32) -> Option<i64>

Converts value toward zero to i64, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toI64 traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. The truncated value is accepted when it is at least -2^63 and below 2^63. Both bounds are powers of two and so are exact in binary32. A bound converted from i64.MAX would round outward and wrongly admit an overflowing value.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

toIsize#

pub fn toIsize(value: f32) -> isize

Converts value toward zero to isize. Traps for NaN, infinity, or a result outside the isize range.

checkedToIsize#

pub fn checkedToIsize(value: f32) -> Option<isize>

Converts value toward zero to isize, or returns None when the truncated result is out of range.

When to use#

Use this function when a NaN, an infinity, or an out-of-range magnitude is input data rather than a program error. toIsize traps on exactly the inputs this function reports as None.

Details#

The fraction is discarded first, so the range test applies to the truncated value: a magnitude below one is in range and yields zero. isize follows the selected target's pointer width, so the bounds follow it too. The truncated value is accepted when it is at least -2^31 and below 2^31 on a 32-bit target, or at least -2^63 and below 2^63 on a 64-bit one.

Every bound is a power of two and so is exact in binary32. A bound converted from isize.MAX would round outward and wrongly admit an overflowing value, and a bound fixed at 64-bit width would admit values that trap on a 32-bit target.

Gotchas#

NaN and either infinity return None. A value in (-1.0, -0.0] truncates to negative zero and converts to 0, so its sign is discarded rather than rejected.

Category: Numbers.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.