The IEEE 754 Companions (BigFloat)
Beyond the arithmetic and the functions, IEEE 754 asks a format for a set of
small operations that numerical code reaches for constantly. They are in
decimo.bigfloat.ieee, which is where they are imported from, and each one is
also a method on the value:
| Function | What it gives |
|---|---|
next_plus(x, p) | The smallest value above x at p bits |
next_minus(x, p) | The largest value below it |
next_toward(x, y, p) | One step from x in the direction of y |
logb(x) | floor(log2(abs(x))), as a BigInt |
scaleb(x, n) | x * 2^n, exactly |
copy_sign(x, y) | x with the sign of y |
copy_abs(x), copy_negate(x) | The sign dropped, the sign flipped |
number_class(x) | +Normal, -Zero, NaN, and so on |
is_integer(x) | Whether x is a whole number |
truncate(x), floor(x), ceil(x) | The three named roundings to a whole number |
round_to_integer(x, mode) | The same in any of the seven modes |
fma(x, y, z, p, mode) | x * y + z with a single rounding |
remainder(x, y, p) | x - y*n, n the nearest integer |
fmod(x, y, p) | x - y*n, n the quotient truncated |
from decimo import BigFloat
from decimo.bigfloat.ieee import fma, next_plus, remainder
var one = BigFloat.from_float64(1.0)
print(next_plus(one, 53)) # 1 + 2^-52
print(one.next_minus(53)) # 1 - 2^-53, half a step away
print(String(BigFloat.from_float64(12.0).logb())) # 3
print(one.scaleb(10)) # 1024, nothing computed
print(BigFloat.from_string("-0.5", 53).ceil()) # -0, the sign surviving
print(remainder(BigFloat.from_float64(5.0), BigFloat.from_float64(3.0), 53))
# -1: six is nearer to five than three is. `fmod` of the same pair is 2.
fma is the one with substance. x * y + z written out rounds the product
before the addition sees it, and a product that nearly cancels with z loses
exactly the bits the answer is made of. Here the product is formed exactly —
it is an integer times a power of two, so there is nothing to round — and only
the sum is rounded:
var above = next_plus(one, 53) # 1 + 2^-52
var product = above * above # rounded: 1 + 2^-51
print(product + (-product)) # 0: the two-step answer
print(fma(above, above, -product, 53)) # 2^-104: what the rounding dropped
Two of these differ from a double, and both follow from the type rather than
from a choice. number_class never answers +Subnormal or -Subnormal: a
significand here always holds its full precision, so every finite non-zero
value is normal. And next_plus and next_minus step through an exponent
range as wide as an Int, so the ends they reach are not a double’s —
next_plus(BigFloat.zero(), 53) is 2^(Int.MIN + 52) where a double answers
2^-1074. Within that range the two agree bit for bit, which is how these are
tested.
logb returns a BigInt rather than an Int because the position of the
leading bit is exponent + precision - 1, and that sum can be outside an
Int while the value itself is an ordinary one. It has no answer for a zero,
an infinity or a NaN, where the standard’s answers are infinities and a NaN,
and raises instead — as the decimal logb() does.