silk/f64

IEEE binary64 values and Silk's default floating-point arithmetic.

When to use

Use f64 for general floating-point calculations and literals without another numeric context. Choose f32 when binary32 storage or interchange is an explicit constraint, not merely as a speculative optimization.

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 binary64 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. toF32 can round a finite value or produce infinity.

Examples

Check floating-point boundaries without losing their representation

import silk.f64 as f64

pub fn main() -> i32 {
  if f64.toBits(f64.round(-0.25)) != f64.toBits(-0.0) {
    return 1
  }
  if !f64.isNaN(f64.sqrt(-1.0)) {
    return 2
  }
  return 42
}

Import as f64 with import silk.f64.

Public declarations: 50.

MAX

pub const MAX: f64

The largest finite f64 value.

MIN

pub const MIN: f64

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

EPSILON

pub const EPSILON: f64

The distance from 1.0 to the next larger f64 value.

INFINITY

pub const INFINITY: f64

Positive infinity with the binary64 bit pattern 0x7FF0000000000000.

Details

No source literal spells infinity directly. This initializer deliberately exceeds MAX, and decimal-to-binary64 rounding produces the infinity encoding.

PI

pub const PI: f64

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

E

pub const E: f64

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

negate

pub fn negate(value: f64) -> f64

Returns value with its sign reversed.

add

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

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

subtract

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

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

multiply

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

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

divide

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

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: f64, right: f64) -> f64

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: f64, right: f64) -> bool

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

notEquals

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

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

lessThan

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

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

lessOrEqual

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

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

greaterThan

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

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

greaterOrEqual

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

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

isNaN

pub fn isNaN(value: f64) -> bool

Returns true when value is a NaN.

isInfinite

pub fn isInfinite(value: f64) -> bool

Returns true when value is positive or negative infinity.

isFinite

pub fn isFinite(value: f64) -> bool

Returns true when value is neither infinity nor NaN.

isNormal

pub fn isNormal(value: f64) -> bool

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

isSubnormal

pub fn isSubnormal(value: f64) -> bool

Returns true when value is finite and has subnormal magnitude.

isSignNegative

pub fn isSignNegative(value: f64) -> bool

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

totalOrder

pub fn totalOrder(left: f64, right: f64) -> 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: f64) -> u64

Reinterprets a value as its exact 64-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: u64) -> f64

Reinterprets an arbitrary 64-bit pattern as f64 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: f64) -> f64

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: f64) -> f64

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

copysign

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

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: f64) -> f64

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: f64) -> f64

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

ceil

pub fn ceil(value: f64) -> f64

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

round

pub fn round(value: f64) -> f64

Rounds to the nearest integral f64, 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: f64, right: f64) -> f64

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: f64, right: f64) -> f64

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: f64) -> f64

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: f64) -> f64

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: f64) -> f32

Converts to binary32 with round-to-nearest ties-to-even.

Details

A finite value too large for binary32 becomes infinity; NaN remains NaN.

toF64

pub fn toF64(value: f64) -> f64

Returns the same binary64 value unchanged.

toU8

pub fn toU8(value: f64) -> u8

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

toU16

pub fn toU16(value: f64) -> u16

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

toU32

pub fn toU32(value: f64) -> u32

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

toU64

pub fn toU64(value: f64) -> u64

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

toUsize

pub fn toUsize(value: f64) -> usize

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

toI8

pub fn toI8(value: f64) -> i8

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

toI16

pub fn toI16(value: f64) -> i16

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

toI32

pub fn toI32(value: f64) -> i32

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

toI64

pub fn toI64(value: f64) -> i64

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

toIsize

pub fn toIsize(value: f64) -> isize

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