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