silk/f32

IEEE binary32 values with deterministic representation, classification, and math operations.

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.

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 evaluator, native, and WebAssembly execution agree on their bits.

Gotchas

Converting to an integer discards the fractional part and traps for NaN, infinity, or a value outside the destination range. Converting a large integer to f32 can round it.

Examples

Inspect a binary32 boundary by its bits

import silk.f32 as 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 2
  }
  return 42
}

Import as f32 with import silk.f32.

Public declarations: 50.

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 directly. This initializer deliberately exceeds MAX, and decimal-to-binary32 rounding produces the infinity encoding.

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.

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 and the evaluator reproduces the same bits.

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.

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.

toU16

pub fn toU16(value: f32) -> u16

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

toU32

pub fn toU32(value: f32) -> u32

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

toU64

pub fn toU64(value: f32) -> u64

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

toUsize

pub fn toUsize(value: f32) -> usize

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

toI8

pub fn toI8(value: f32) -> i8

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

toI16

pub fn toI16(value: f32) -> i16

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

toI32

pub fn toI32(value: f32) -> i32

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

toI64

pub fn toI64(value: f32) -> i64

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

toIsize

pub fn toIsize(value: f32) -> isize

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