Home / Docs / Specification / 29. Numerics

29.3 Operations

Release v0.4.0

All operations are total: none fails, none has a precondition, and none generates a proof obligation. Every result is the IEEE 754-2019 result in roundTiesToEven, with a NaN result replaced by the canonical NaN. The rounding mode cannot be changed.

  1. Operators. +, -, * and / on two F64 operands are the IEEE operations, correctly rounded. Unary - is IEEE negate: it flips the sign bit, exactly. mod on F64 is U2001, with a repair to rem.

  2. Division by zero gives infinities or NaN, not a failure. 1.0 / 0.0 is infinity(), 1.0 / -0.0 is -infinity(), and 0.0 / 0.0 is NaN. An F64 division has no division obligation, and float code runs under any program counter (spec/07 §3).

  3. Methods. These are built-in methods resolved by the receiver, with labeled arguments in the order written here:

    Method Result Semantics
    x.abs() F64 clears the sign bit: (-0.0).abs() is 0.0
    x.sqrt() F64 IEEE squareRoot; (-0.0).sqrt() is -0.0; a negative argument gives NaN
    x.fma(times: y, plus: z) F64 IEEE fusedMultiplyAdd: x * y + z rounded once
    x.rem(by: y) F64 x - y * n with n the quotient x / y truncated toward zero, computed exactly: the result has the sign of x, (-1.0).rem(by: 1.0) is -0.0, and x.rem(by: 0.0) and infinity().rem(by: y) are NaN
    x.floor(), x.ceil(), x.trunc() F64 IEEE roundToIntegral toward -∞, +∞ and 0: (-0.5).ceil() is -0.0
    x.round_half_even() F64 IEEE roundToIntegralTiesToEven: 0.5 gives 0.0, 1.5 and 2.5 give 2.0, -0.5 gives -0.0
    x.round_half_away() F64 IEEE roundToIntegralTiesToAway: 2.5 gives 3.0, -0.5 gives -1.0, 0.49999999999999994 gives 0.0
    x.copy_sign(from: y) F64 x with the sign bit of y
    x.ieee_min(other: y), x.ieee_max(other: y) F64 IEEE 754-2019 minimum and maximum: NaN when either is NaN, and -0.0 below 0.0
    x.clamp(lo: a, hi: b) F64 x.ieee_max(other: a).ieee_min(other: b): NaN when any of the three is NaN, b when a > b
    x.ieee_eq(other: y), ieee_ne, ieee_lt, ieee_le, ieee_gt, ieee_ge Bool the IEEE quiet comparison predicates: -0.0 equals 0.0, NaN is unordered, so every one but ieee_ne is false when an operand is NaN
    x.is_nan(), x.is_finite(), x.is_infinite(), x.is_sign_negative() Bool classification; nan().is_sign_negative() is false
    x.is_zero(), x.is_positive_zero(), x.is_negative_zero() Bool x is 0.0 or -0.0; x is 0.0; x is -0.0
    x.to_bits() U64 the bits; for a NaN, 0x7FF8000000000000

    The label of copy_sign's argument is the keyword from, which a call's argument may take as its label in edition 0.3, and nothing else may (spec/02). A rounding method keeps NaN, the infinities and the sign of a zero. A method name that is not in this table, on an F64 receiver, resolves as a function of the package (spec/10 §5).

  4. No round(). There is no method named round: the name says which tie rule runs.

  5. min and max of the prelude order by §5: min(-0.0, b: 0.0) is -0.0, max(nan(), b: 1.0) is NaN, and min(nan(), b: 1.0) is 1.0, since NaN is the greatest F64. A clamp written with them, min(max(x, b: lo), b: hi), maps NaN to hi; x.clamp(lo:, hi:) keeps NaN.

  6. abs of the prelude stays abs(x: Int) -> Int: abs(x) with an F64 is U2001; x.abs() is the method.

  7. No transcendental functions yet: exp, log, sin, cos, tan, pow and the others wait for a correctly rounded implementation (ADR 0114 rule 18). No F64 function is ever computed by the platform's math library (§6).

  8. No floating-point environment. There are no exception flags, no traps and no rounding modes in the language.

  9. The prelude gains:

    Function Type Meaning
    nan() F64 the canonical NaN
    infinity() F64 the positive infinity
    f64_from_bits(bits: U64) F64 the value with those bits; any NaN gives the canonical NaN
    parse_f64(t: Text) F64 fails ParseError §7 rule 3
    as_f64(j: Json) Option[F64] §10
    json_number(x: F64) Option[Json] §10

    A package declaration MAY reuse one of these names and wins over it, as for any prelude name (spec/10 §11 rule 5).