Skip to content

How it works

A Decimal is a fixed-point number:

// value = (neg ? -1 : 1) * coef * 10^(-prec)
type Decimal struct {
    coef bint
    neg  bool
    prec uint8 // 0 <= prec <= 19
}

// 123.456  -> neg = false, coef = 123456, prec = 3
// -123.456 -> neg = true,  coef = 123456, prec = 3

The coefficient is a bint, which holds one of two representations:

type bint struct {
    // set when the value doesn't fit in u128, or was computed with math/big
    bigInt *big.Int

    // 0 <= u128 <= 2^128 - 1
    u128 u128
}

Range

u128 is a pair of uint64 values and holds coefficients up to 2^128 − 1 = 340282366920938463463374607431768211455. That covers every coefficient of up to 38 digits and some of 39. Because the coefficient includes the decimal places, the largest value depends on prec:

prec Largest magnitude in 128 bits
0 340282366920938463463374607431768211455
2 3402823669209384634633746074317682114.55
19 34028236692093846346.3374607431768211455

Fast path

On the fast path, operations use 64-bit and 128-bit integer arithmetic, with a 256-bit intermediate result for Mul and Div, and don't allocate. Each operation uses the fast path under these conditions:

Operation Condition
Parse the coefficient fits in 128 bits, which is always true for up to 38 digits
Add, Sub both operands, scaled to the larger prec, and the result fit
Mul both operands and the result, truncated to at most 19 decimal places, fit
Div both operands fit, and the quotient fits at prec = 19, the default precision, so it is below about 3.4 × 10^19

Div always returns 19 decimal places, so its limit doesn't depend on the precision of the operands:

// 34028236692093846346 / 1 -> fast path, no allocation
// 34028236692093846347 / 1 -> the quotient's coefficient exceeds 2^128 - 1: math/big, allocates

Lowering the default precision with SetDefaultPrecision raises this limit. At a default precision of 2, the quotient can reach about 3.4 × 10^36.

A value computed with math/big keeps using math/big, even if it would fit in 128 bits. Operations on it allocate, ToHiLo returns ok = false, and Int64 returns ErrIntPartOverflow. For example, 10^39 - (10^39 - 1) returns 1 stored as math/big.

math/big fallback

If an operand or the result doesn't fit, the whole operation is computed again with math/big. This is correct but slower, and it allocates. In the benchmarks, the fallback allocates 4–7 times per operation, and udecimal is the fastest library in only 1 of those 6 cases.

Truncation

When a result has more decimal places than the precision allows, udecimal truncates the extra digits, which rounds toward zero. It doesn't choose a rounding mode for you, because the modes give different results for the same input and financial code often has to follow a specific one. To round, call one of the rounding methods.