Skip to content

Precision and rounding

A Decimal consists of a sign, a coefficient and a precision:

value = (neg ? -1 : 1) × coef × 10^(-prec)

prec is the number of decimal places, at most 19. For example, 123.456 has coef = 123456 and prec = 3.

Result precision

Operation Decimal places in the result
Add, Sub the larger prec of the two operands
Mul the sum of both prec values, truncated to 19
Div 19, truncated

Truncation drops the extra digits, which rounds toward zero. Results are not rounded unless you call a rounding method.

fmt.Println(udecimal.MustParse("1.23").Div(udecimal.MustParse("4.12475")))
fmt.Println(udecimal.MustParse("1.23").Div(udecimal.MustParse("0")))
// Output:
// 0.2981998909024789381 <nil>
// 0 can't divide by zero

Operations whose operands and result fit in 128 bits don't allocate; other operations use math/big. See How it works for the exact limits.

Default precision

SetDefaultPrecision(prec) sets the maximum number of decimal places for the whole program, for example to match a currency. Call it once at startup. It panics if prec is 0 or greater than 19.

udecimal.SetDefaultPrecision(10)
defer udecimal.SetDefaultPrecision(19)

a := udecimal.MustParse("1.23")
b := udecimal.MustParse("4.12475")
c, _ := a.Div(b)
fmt.Println(c)
// Output:
// 0.2981998909

The default precision also applies to input. Parse, NewFromInt64, NewFromUint64 and NewFromHiLo return ErrPrecOutOfRange for a value with more decimal places than the default precision:

fmt.Println(udecimal.NewFromInt64(123, 3))
fmt.Println(udecimal.NewFromInt64(12345, 20))
// Output:
// 0.123 <nil>
// 0 precision out of range. Only support maximum 19 digits after the decimal point

To truncate such input instead, see Parse modes.

Rounding

udecimal doesn't round implicitly. To round a value, call one of these methods. Each takes the number of decimal places to keep.

Method Rule 1.12345 → 4 places 1.12335 → 4 places 1.5 → 0 -1.5 → 0
RoundBank half to even 1.1234 1.1234 2 -2
RoundHAZ half away from zero 1.1235 1.1234 2 -2
RoundHTZ half toward zero 1.1234 1.1233 1 -1
fmt.Println(udecimal.MustParse("1.12345").RoundBank(4))
fmt.Println(udecimal.MustParse("1.12335").RoundBank(4))
fmt.Println(udecimal.MustParse("1.5").RoundBank(0))
fmt.Println(udecimal.MustParse("-1.5").RoundBank(0))
// Output:
// 1.1234
// 1.1234
// 2
// -2

Other rounding methods

Method Rule Examples
RoundAwayFromZero(prec) any remainder rounds away from zero 1.12 → 1.2, -1.12 → -1.2 (1 place)
Trunc(prec) drops the extra digits 1.23 → 1.2 (1 place)
Floor() toward negative infinity, to an integer 1.23 → 1, -1.23 → -2
Ceil() toward positive infinity, to an integer 1.23 → 2

If the value has fewer decimal places than requested, it is returned unchanged.

fmt.Println(udecimal.MustParse("1.23").Trunc(1))
fmt.Println(udecimal.MustParse("-1.23").Trunc(5))
// Output:
// 1.2
// -1.23

Rounding currency amounts

Round once, at the end, to the number of decimal places of the currency. RoundHAZ(2) rounds ties away from zero. RoundBank(2), also called banker's rounding, rounds ties to the nearest even digit, which avoids a systematic bias when many values are rounded.

// splitting 10.05 between two people
share, _ := udecimal.MustParse("10.05").Div64(2)

fmt.Println(share)
fmt.Println(share.RoundHAZ(2))
fmt.Println(share.RoundBank(2))
// Output:
// 5.025
// 5.03
// 5.02