1# decimal
2
3[](https://github.com/shopspring/decimal/actions/workflows/ci.yml)
4[](https://godoc.org/github.com/shopspring/decimal)
5[](https://goreportcard.com/report/github.com/shopspring/decimal)
6
7Arbitrary-precision fixed-point decimal numbers in go.
8
9_Note:_ Decimal library can "only" represent numbers with a maximum of 2^31 digits after the decimal point.
10
11## Features
12
13 * The zero-value is 0, and is safe to use without initialization
14 * Addition, subtraction, multiplication with no loss of precision
15 * Division with specified precision
16 * Database/sql serialization/deserialization
17 * JSON and XML serialization/deserialization
18
19## Install
20
21Run `go get github.com/shopspring/decimal`
22
23## Requirements
24
25Decimal library requires Go version `>=1.10`
26
27## Documentation
28
29http://godoc.org/github.com/shopspring/decimal
30
31
32## Usage
33
34```go
35package main
36
37import (
38 "fmt"
39 "github.com/shopspring/decimal"
40)
41
42func main() {
43 price, err := decimal.NewFromString("136.02")
44 if err != nil {
45 panic(err)
46 }
47
48 quantity := decimal.NewFromInt(3)
49
50 fee, _ := decimal.NewFromString(".035")
51 taxRate, _ := decimal.NewFromString(".08875")
52
53 subtotal := price.Mul(quantity)
54
55 preTax := subtotal.Mul(fee.Add(decimal.NewFromFloat(1)))
56
57 total := preTax.Mul(taxRate.Add(decimal.NewFromFloat(1)))
58
59 fmt.Println("Subtotal:", subtotal) // Subtotal: 408.06
60 fmt.Println("Pre-tax:", preTax) // Pre-tax: 422.3421
61 fmt.Println("Taxes:", total.Sub(preTax)) // Taxes: 37.482861375
62 fmt.Println("Total:", total) // Total: 459.824961375
63 fmt.Println("Tax rate:", total.Sub(preTax).Div(preTax)) // Tax rate: 0.08875
64}
65```
66
67## Alternative libraries
68
69When working with decimal numbers, you might face problems this library is not perfectly suited for.
70Fortunately, thanks to the wonderful community we have a dozen other libraries that you can choose from.
71Explore other alternatives to find the one that best fits your needs :)
72
73* [cockroachdb/apd](https://github.com/cockroachdb/apd) - arbitrary precision, mutable and rich API similar to `big.Int`, more performant than this library
74* [alpacahq/alpacadecimal](https://github.com/alpacahq/alpacadecimal) - high performance, low precision (12 digits), fully compatible API with this library
75* [govalues/decimal](https://github.com/govalues/decimal) - high performance, zero-allocation, low precision (19 digits)
76* [greatcloak/decimal](https://github.com/greatcloak/decimal) - fork focusing on billing and e-commerce web application related use cases, includes out-of-the-box BSON marshaling support
77
78## FAQ
79
80#### Why don't you just use float64?
81
82Because float64 (or any binary floating point type, actually) can't represent
83numbers such as `0.1` exactly.
84
85Consider this code: http://play.golang.org/p/TQBd4yJe6B You might expect that
86it prints out `10`, but it actually prints `9.999999999999831`. Over time,
87these small errors can really add up!
88
89#### Why don't you just use big.Rat?
90
91big.Rat is fine for representing rational numbers, but Decimal is better for
92representing money. Why? Here's a (contrived) example:
93
94Let's say you use big.Rat, and you have two numbers, x and y, both
95representing 1/3, and you have `z = 1 - x - y = 1/3`. If you print each one
96out, the string output has to stop somewhere (let's say it stops at 3 decimal
97digits, for simplicity), so you'll get 0.333, 0.333, and 0.333. But where did
98the other 0.001 go?
99
100Here's the above example as code: http://play.golang.org/p/lCZZs0w9KE
101
102With Decimal, the strings being printed out represent the number exactly. So,
103if you have `x = y = 1/3` (with precision 3), they will actually be equal to
1040.333, and when you do `z = 1 - x - y`, `z` will be equal to .334. No money is
105unaccounted for!
106
107You still have to be careful. If you want to split a number `N` 3 ways, you
108can't just send `N/3` to three different people. You have to pick one to send
109`N - (2/3*N)` to. That person will receive the fraction of a penny remainder.
110
111But, it is much easier to be careful with Decimal than with big.Rat.
112
113#### Why isn't the API similar to big.Int's?
114
115big.Int's API is built to reduce the number of memory allocations for maximal
116performance. This makes sense for its use-case, but the trade-off is that the
117API is awkward and easy to misuse.
118
119For example, to add two big.Ints, you do: `z := new(big.Int).Add(x, y)`. A
120developer unfamiliar with this API might try to do `z := a.Add(a, b)`. This
121modifies `a` and sets `z` as an alias for `a`, which they might not expect. It
122also modifies any other aliases to `a`.
123
124Here's an example of the subtle bugs you can introduce with big.Int's API:
125https://play.golang.org/p/x2R_78pa8r
126
127In contrast, it's difficult to make such mistakes with decimal. Decimals
128behave like other go numbers types: even though `a = b` will not deep copy
129`b` into `a`, it is impossible to modify a Decimal, since all Decimal methods
130return new Decimals and do not modify the originals. The downside is that
131this causes extra allocations, so Decimal is less performant. My assumption
132is that if you're using Decimals, you probably care more about correctness
133than performance.
134
135## License
136
137The MIT License (MIT)
138
139This is a heavily modified fork of [fpd.Decimal](https://github.com/oguzbilgic/fpd), which was also released under the MIT License.
View as plain text