README
¶
decimal 
Arbitrary-precision fixed-point decimal numbers in go.
NOTE: can "only" represent numbers with a maximum of 2^31 digits after the decimal point.
Features
- the zero-value is 0, and is safe to use without initialization
- addition, subtraction, multiplication with no loss of precision
- division with specified precision
- database/sql serialization/deserialization
- json and xml serialization/deserialization
Install
Run go get github.com/shopspring/decimal
Usage
package main
import (
"fmt"
"github.com/shopspring/decimal"
)
func main() {
price, err := decimal.NewFromString("136.02")
if err != nil {
panic(err)
}
quantity := decimal.NewFromFloat(3)
fee, _ := decimal.NewFromString(".035")
taxRate, _ := decimal.NewFromString(".08875")
subtotal := price.Mul(quantity)
preTax := subtotal.Mul(fee.Add(decimal.NewFromFloat(1)))
total := preTax.Mul(taxRate.Add(decimal.NewFromFloat(1)))
fmt.Println("Subtotal:", subtotal) // Subtotal: 408.06
fmt.Println("Pre-tax:", preTax) // Pre-tax: 422.3421
fmt.Println("Taxes:", total.Sub(preTax)) // Taxes: 37.482861375
fmt.Println("Total:", total) // Total: 459.824961375
fmt.Println("Tax rate:", total.Sub(preTax).Div(preTax)) // Tax rate: 0.08875
}
Documentation
http://godoc.org/github.com/shopspring/decimal
Production Usage
- Spring, since August 14, 2014.
- If you are using this in production, please let us know!
FAQ
Why don't you just use float64?
Because float64s (or any binary floating point type, actually) can't represent numbers such as 0.1 exactly.
Consider this code: http://play.golang.org/p/TQBd4yJe6B You might expect that
it prints out 10, but it actually prints 9.999999999999831. Over time,
these small errors can really add up!
Why don't you just use big.Rat?
big.Rat is fine for representing rational numbers, but Decimal is better for representing money. Why? Here's a (contrived) example:
Let's say you use big.Rat, and you have two numbers, x and y, both
representing 1/3, and you have z = 1 - x - y = 1/3. If you print each one
out, the string output has to stop somewhere (let's say it stops at 3 decimal
digits, for simplicity), so you'll get 0.333, 0.333, and 0.333. But where did
the other 0.001 go?
Here's the above example as code: http://play.golang.org/p/lCZZs0w9KE
With Decimal, the strings being printed out represent the number exactly. So,
if you have x = y = 1/3 (with precision 3), they will actually be equal to
0.333, and when you do z = 1 - x - y, z will be equal to .334. No money is
unaccounted for!
You still have to be careful. If you want to split a number N 3 ways, you
can't just send N/3 to three different people. You have to pick one to send
N - (2/3*N) to. That person will receive the fraction of a penny remainder.
But, it is much easier to be careful with Decimal than with big.Rat.
Why isn't the API similar to big.Int's?
big.Int's API is built to reduce the number of memory allocations for maximal performance. This makes sense for its use-case, but the trade-off is that the API is awkward and easy to misuse.
For example, to add two big.Ints, you do: z := new(big.Int).Add(x, y). A
developer unfamiliar with this API might try to do z := a.Add(a, b). This
modifies a and sets z as an alias for a, which they might not expect. It
also modifies any other aliases to a.
Here's an example of the subtle bugs you can introduce with big.Int's API: https://play.golang.org/p/x2R_78pa8r
In contrast, it's difficult to make such mistakes with decimal. Decimals
behave like other go numbers types: even though a = b will not deep copy
b into a, it is impossible to modify a Decimal, since all Decimal methods
return new Decimals and do not modify the originals. The downside is that
this causes extra allocations, so Decimal is less performant. My assumption
is that if you're using Decimals, you probably care more about correctness
than performance.
License
The MIT License (MIT)
This is a heavily modified fork of fpd.Decimal, which was also released under the MIT License.
Documentation
¶
Overview ¶
Package decimal implements an arbitrary precision fixed-point decimal.
To use as part of a struct:
type Struct struct {
Number Decimal
}
The zero-value of a Decimal is 0, as you would expect.
The best way to create a new Decimal is to use decimal.NewFromString, ex:
n, err := decimal.NewFromString("-123.4567")
n.String() // output: "-123.4567"
NOTE: This can "only" represent numbers with a maximum of 2^31 digits after the decimal point.
Index ¶
- Variables
- type Decimal
- func Max(first Decimal, rest ...Decimal) Decimal
- func Min(first Decimal, rest ...Decimal) Decimal
- func New(value int64, exp int32) Decimal
- func NewFromBigInt(value *big.Int, exp int32) Decimal
- func NewFromFloat(value float64) Decimal
- func NewFromFloatWithExponent(value float64, exp int32) Decimal
- func NewFromString(value string) (Decimal, error)
- func (d Decimal) Abs() Decimal
- func (d Decimal) Add(d2 Decimal) Decimal
- func (d Decimal) BigInt() *big.Int
- func (d Decimal) Ceil() Decimal
- func (d Decimal) Cmp(d2 Decimal) int
- func (d Decimal) Div(d2 Decimal) Decimal
- func (d Decimal) Equals(d2 Decimal) bool
- func (d Decimal) Exponent() int32
- func (d Decimal) Float64() (f float64, exact bool)
- func (d Decimal) Floor() Decimal
- func (d Decimal) IntPart() int64
- func (d Decimal) MarshalJSON() ([]byte, error)
- func (d Decimal) MarshalText() (text []byte, err error)
- func (d Decimal) Mod(d2 Decimal) Decimal
- func (d Decimal) Mul(d2 Decimal) Decimal
- func (d Decimal) Rat() *big.Rat
- func (d Decimal) Round(places int32) Decimal
- func (d *Decimal) Scan(value interface{}) error
- func (d Decimal) String() string
- func (d Decimal) StringFixed(places int32) string
- func (d Decimal) StringScaled(exp int32) string
- func (d Decimal) Sub(d2 Decimal) Decimal
- func (d Decimal) Truncate(precision int32) Decimal
- func (d *Decimal) UnmarshalJSON(decimalBytes []byte) error
- func (d *Decimal) UnmarshalText(text []byte) error
- func (d Decimal) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
var DivisionPrecision = 16
DivisionPrecision is the number of decimal places in the result when it doesn't divide exactly.
Example:
d1 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3) d1.String() // output: "0.6666666666666667" d2 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(30000) d2.String() // output: "0.0000666666666667" d3 := decimal.NewFromFloat(20000).Div(decimal.NewFromFloat(3) d3.String() // output: "6666.6666666666666667" decimal.DivisionPrecision = 3 d4 := decimal.NewFromFloat(2).Div(decimal.NewFromFloat(3) d4.String() // output: "0.667"
var Zero = New(0, 1)
Zero constant, to make computations faster.
Functions ¶
This section is empty.
Types ¶
type Decimal ¶
type Decimal struct {
// contains filtered or unexported fields
}
Decimal represents a fixed-point decimal. It is immutable. number = value * 10 ^ exp
func Max ¶
Returns the largest Decimal that was passed in the arguments.
To call this function with an array, you must do:
Max(arr[0], arr[1:]...)
This makes it harder to accidentally call Max with 0 arguments.
func Min ¶
Returns the smallest Decimal that was passed in the arguments.
To call this function with an array, you must do:
Min(arr[0], arr[1:]...)
This makes it harder to accidentally call Min with 0 arguments.
func NewFromBigInt ¶
NewFromBigInt returns a new fixed-point decimal, value * 10 ^ exp.
func NewFromFloat ¶
NewFromFloat converts a float64 to Decimal.
Example:
NewFromFloat(123.45678901234567).String() // output: "123.4567890123456" NewFromFloat(.00000000000000001).String() // output: "0.00000000000000001"
NOTE: this will panic on NaN, +/-inf
func NewFromFloatWithExponent ¶
NewFromFloatWithExponent converts a float64 to Decimal, with an arbitrary number of fractional digits.
Example:
NewFromFloatWithExponent(123.456, -2).String() // output: "123.46"
func NewFromString ¶
NewFromString returns a new Decimal from a string representation.
Example:
d, err := NewFromString("-123.45")
d2, err := NewFromString(".0001")
func (Decimal) Cmp ¶
Cmp compares the numbers represented by d and d2 and returns:
-1 if d < d2 0 if d == d2 +1 if d > d2
func (Decimal) Div ¶
Div returns d / d2. If it doesn't divide exactly, the result will have DivisionPrecision digits after the decimal point.
func (Decimal) Float64 ¶
Float64 returns the nearest float64 value for d and a bool indicating whether f represents d exactly. For more details, see the documentation for big.Rat.Float64
func (Decimal) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (Decimal) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface for XML serialization.
func (Decimal) Round ¶
Round rounds the decimal to places decimal places. If places < 0, it will round the integer part to the nearest 10^(-places).
Example:
NewFromFloat(5.45).Round(1).String() // output: "5.5" NewFromFloat(545).Round(-1).String() // output: "550"
func (Decimal) String ¶
String returns the string representation of the decimal with the fixed point.
Example:
d := New(-12345, -3) println(d.String())
Output:
-12.345
func (Decimal) StringFixed ¶
StringFixed returns a rounded fixed-point string with places digits after the decimal point.
Example:
NewFromFloat(0).StringFixed(2) // output: "0.00" NewFromFloat(0).StringFixed(0) // output: "0" NewFromFloat(5.45).StringFixed(0) // output: "5" NewFromFloat(5.45).StringFixed(1) // output: "5.5" NewFromFloat(5.45).StringFixed(2) // output: "5.45" NewFromFloat(5.45).StringFixed(3) // output: "5.450" NewFromFloat(545).StringFixed(-1) // output: "550"
func (Decimal) StringScaled ¶
NOTE: buggy, unintuitive, and DEPRECATED! Use StringFixed instead. StringScaled first scales the decimal then calls .String() on it.
func (Decimal) Truncate ¶
Truncate truncates off digits from the number, without rounding.
NOTE: precision is the last digit that will not be truncated (must be >= 0).
Example:
decimal.NewFromString("123.456").Truncate(2).String() // "123.45"
func (*Decimal) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface.
func (*Decimal) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization.
Source Files