silk.num.f64.

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. The Order conformance of f64 uses the same total order, so List<f64>.sort puts negative NaNs first, then -0.0 before +0.0, and positive NaNs last.

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

Examples#

Check floating-point boundaries without losing their representation#

import silk.num.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 1
  }
  return 0
}

Import as f64 with import silk.num.f64.

Public declarations: 72.

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, and a literal that rounds to infinity is rejected. Doubling MAX overflows to the infinity encoding.

NAN#

pub const NAN: f64

The canonical quiet NaN, with the binary64 bit pattern 0x7FF8000000000000.

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: 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.

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 f64, which sorting and binary search use, follows it.

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.

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.

tan#

pub fn tan(value: f64) -> f64

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

Details#

The argument is reduced by pi/2 with up to 1,216 bits of 2/pi, 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: f64) -> f64

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

Approximates the angle of the point (x, y) from the positive x axis within two units 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: f64) -> f64

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

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

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

Details#

A result too large for f64 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: f64) -> f64

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

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

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

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

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 integer 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: 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.

checkedToU8#

pub fn checkedToU8(value: f64) -> 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 binary64. 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: f64) -> u16

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

checkedToU16#

pub fn checkedToU16(value: f64) -> 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 binary64. 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: f64) -> u32

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

checkedToU32#

pub fn checkedToU32(value: f64) -> 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 binary64. 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: f64) -> u64

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

checkedToU64#

pub fn checkedToU64(value: f64) -> 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 binary64. 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: f64) -> usize

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

checkedToUsize#

pub fn checkedToUsize(value: f64) -> 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 binary64. 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: f64) -> i8

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

checkedToI8#

pub fn checkedToI8(value: f64) -> 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 binary64. 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: f64) -> i16

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

checkedToI16#

pub fn checkedToI16(value: f64) -> 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 binary64. 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: f64) -> i32

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

checkedToI32#

pub fn checkedToI32(value: f64) -> 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 binary64. 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: f64) -> i64

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

checkedToI64#

pub fn checkedToI64(value: f64) -> 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 binary64. 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: f64) -> isize

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

checkedToIsize#

pub fn checkedToIsize(value: f64) -> 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 binary64. 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.