Comparison
This page compares udecimal with four other Go decimal libraries, using the versions benchmarked on the Performance page.
Choosing a library
- udecimal suits code where 19 decimal places are enough and arithmetic should be fast and allocation-free.
- shopspring/decimal suits code that needs unbounded precision.
Add,SubandMulare exact. See Migrating from shopspring to switch. - cockroachdb/apd implements the General Decimal Arithmetic model, with contexts, conditions and traps.
- govalues/decimal suits code where every value has at most 19 digits in total, including the integer part.
- ericlagergren/decimal provides arbitrary precision with contexts, using pointers.
Summary
| Library | Representation | Digits kept | Extra digits | Allocations¹ |
|---|---|---|---|---|
| udecimal | 128-bit, math/big fallback |
19 decimal places | truncated | 0 / 0 / 0 / 0 |
| shopspring v1.6.0 | big.Int and exponent |
all | Div rounds to 16 |
2 / 2 / 2 / 7 |
| apd v3.2.3 | big.Int and context |
set by context | rounded by context | 0 / 0 / 0 / 2 |
| govalues v0.1.36 | uint64 |
19 in total | rounded, half to even | 0 / 0 / 0 / 2 |
| ericlagergren | big.Int and context |
set by context, 16 by default | rounded by context | 0 / 0 / 0 / 2 |
¹ Allocations per Add / Sub / Mul / Div for inputs of up to 19 digits. See
Arithmetic.
Libraries
udecimal
udecimal is a fixed-point type with a 128-bit coefficient, which holds values of up to 38 digits in total.
Arithmetic on these values doesn't allocate within the limits described in How it works; larger
values use math/big. Results have at most 19 decimal places. Extra digits are truncated, and other rounding modes
are explicit method calls. Values are immutable, and operations that can fail, such as Div, return an error.
shopspring/decimal
shopspring/decimal is a general-purpose library with no upper limit on size. Div rounds the quotient half away
from zero to DivisionPrecision decimal places, 16 by default. In the benchmarks it allocates twice per Add, Sub
and Mul, and 7 times per Div. Values are immutable.
cockroachdb/apd
apd implements much of the General Decimal Arithmetic specification. A Context sets the precision, the rounding
mode and the traps, and results are rounded to that precision. Operations take pointers, for example
ctx.Add(z, x, y), and return (Condition, error).
govalues/decimal
govalues/decimal stores the coefficient in a uint64, so a value has at most 19 digits in total, counting both sides
of the decimal point. Longer values are rounded half to even, and a result that would lose an integer digit returns
an overflow error. Add, Sub and Mul don't allocate. Quo falls back to big.Int when the uint64 computation
overflows; in the benchmarks, Div allocates twice and is the slowest of the five libraries. Operations return
(Decimal, error).
ericlagergren/decimal
ericlagergren/decimal provides arbitrary precision with a context, similar to apd. Operations work on pointers and
overwrite the receiver, for example z.Add(x, y). If no precision is set, a context keeps 16 significant digits.
govalues and inputs over 19 digits
The govalues documentation states that Parse returns a
"possibly rounded" decimal. In v0.1.36, an input with more than 19 digits in total is rounded to 19 digits without
an error. If the integer part has 19 digits, the fractional part is lost entirely:
import govalues "github.com/govalues/decimal"
d, err := govalues.Parse("1234567890123456789.1234567890123456879")
// d = 1234567890123456789, err = nil
d, err = udecimal.Parse("1234567890123456789.1234567890123456879")
// d = 1234567890123456789.1234567890123456879, err = nil
If the integer part is shorter, the fraction is rounded instead: 12345.1234567890123456789 becomes
12345.12345678901235. An integer part of more than 19 digits returns an error. For this reason, the
Beyond 19 digits benchmarks list govalues as "can't represent" instead of timing
it on a different number. This behavior is covered by
TestGovaluesLosesFraction.