Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

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