README
¶
decimal
Arbitrary-precision fixed-point decimal numbers in go.
Note: Decimal library 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
Requirements
Decimal library requires Go version >=1.7
Usage
package main
import (
"fmt"
"github.com/shopspring/decimal"
)
func main() {
price, err := decimal.NewFromString("136.02")
if err != nil {
panic(err)
}
quantity := decimal.NewFromInt(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 float64 (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.
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"
To use Decimal as part of a struct:
type Struct struct {
Number Decimal
}
Note: This can "only" represent numbers with a maximum of 2^31 digits after the decimal point.
Index ¶
- Variables
- func RescalePair(d1 Decimal, d2 Decimal) (Decimal, Decimal)
- type Decimal
- func Avg(first Decimal, rest ...Decimal) 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 NewFromFloat32(value float32) Decimal
- func NewFromFloatWithExponent(value float64, exp int32) Decimal
- func NewFromInt(value int64) Decimal
- func NewFromInt32(value int32) Decimal
- func NewFromString(value string) (Decimal, error)
- func RequireFromString(value string) Decimal
- func Sum(first Decimal, rest ...Decimal) Decimal
- func (d Decimal) Abs() Decimal
- func (d Decimal) Add(d2 Decimal) Decimal
- func (d Decimal) Atan() Decimal
- func (d Decimal) BigFloat() *big.Float
- func (d Decimal) BigInt() *big.Int
- func (d Decimal) Ceil() Decimal
- func (d Decimal) Cmp(d2 Decimal) int
- func (d Decimal) Coefficient() *big.Int
- func (d Decimal) Cos() Decimal
- func (d Decimal) Div(d2 Decimal) Decimal
- func (d Decimal) DivRound(d2 Decimal, precision int32) Decimal
- func (d Decimal) Equal(d2 Decimal) bool
- 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) GobDecode(data []byte) error
- func (d Decimal) GobEncode() ([]byte, error)
- func (d Decimal) GreaterThan(d2 Decimal) bool
- func (d Decimal) GreaterThanOrEqual(d2 Decimal) bool
- func (d Decimal) IntPart() int64
- func (d Decimal) IsInteger() bool
- func (d Decimal) IsNegative() bool
- func (d Decimal) IsPositive() bool
- func (d Decimal) IsZero() bool
- func (d Decimal) LessThan(d2 Decimal) bool
- func (d Decimal) LessThanOrEqual(d2 Decimal) bool
- func (d Decimal) MarshalBinary() (data []byte, err error)
- 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) Neg() Decimal
- func (d Decimal) Pow(d2 Decimal) Decimal
- func (d Decimal) QuoRem(d2 Decimal, precision int32) (Decimal, Decimal)
- func (d Decimal) Rat() *big.Rat
- func (d Decimal) Round(places int32) Decimal
- func (d Decimal) RoundBank(places int32) Decimal
- func (d Decimal) RoundCash(interval uint8) Decimal
- func (d *Decimal) Scan(value interface{}) error
- func (d Decimal) Shift(shift int32) Decimal
- func (d Decimal) Sign() int
- func (d Decimal) Sin() Decimal
- func (d Decimal) String() string
- func (d Decimal) StringFixed(places int32) string
- func (d Decimal) StringFixedBank(places int32) string
- func (d Decimal) StringFixedCash(interval uint8) string
- func (d Decimal) StringScaled(exp int32) string
- func (d Decimal) Sub(d2 Decimal) Decimal
- func (d Decimal) Tan() Decimal
- func (d Decimal) Truncate(precision int32) Decimal
- func (d *Decimal) UnmarshalBinary(data []byte) error
- func (d *Decimal) UnmarshalJSON(decimalBytes []byte) error
- func (d *Decimal) UnmarshalText(text []byte) error
- func (d Decimal) Value() (driver.Value, error)
- type NullDecimal
Examples ¶
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 MarshalJSONWithoutQuotes = false
MarshalJSONWithoutQuotes should be set to true if you want the decimal to be JSON marshaled as a number, instead of as a string. WARNING: this is dangerous for decimals with many digits, since many JSON unmarshallers (ex: Javascript's) will unmarshal JSON numbers to IEEE 754 double-precision floating point numbers, which means you can potentially silently lose precision.
var Zero = New(0, 1)
Zero constant, to make computations faster. Zero should never be compared with == or != directly, please use decimal.Equal or decimal.Cmp instead.
Functions ¶
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 ¶
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 ¶
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 Decimal from a big.Int, value * 10 ^ exp
func NewFromFloat ¶
NewFromFloat converts a float64 to Decimal.
The converted number will contain the number of significant digits that can be represented in a float with reliable roundtrip. This is typically 15 digits, but may be more in some cases. See https://www.exploringbinary.com/decimal-precision-of-binary-floating-point-numbers/ for more information.
For slightly faster conversion, use NewFromFloatWithExponent where you can specify the precision in absolute terms.
NOTE: this will panic on NaN, +/-inf
Example ¶
fmt.Println(NewFromFloat(123.123123123123).String()) fmt.Println(NewFromFloat(.123123123123123).String()) fmt.Println(NewFromFloat(-1e13).String())
Output: 123.123123123123 0.123123123123123 -10000000000000
func NewFromFloat32 ¶ added in v1.1.0
NewFromFloat32 converts a float32 to Decimal.
The converted number will contain the number of significant digits that can be represented in a float with reliable roundtrip. This is typically 6-8 digits depending on the input. See https://www.exploringbinary.com/decimal-precision-of-binary-floating-point-numbers/ for more information.
For slightly faster conversion, use NewFromFloatWithExponent where you can specify the precision in absolute terms.
NOTE: this will panic on NaN, +/-inf
Example ¶
fmt.Println(NewFromFloat32(123.123123123123).String()) fmt.Println(NewFromFloat32(.123123123123123).String()) fmt.Println(NewFromFloat32(-1e13).String())
Output: 123.12312 0.123123124 -10000000000000
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 NewFromInt ¶ added in v1.2.1
NewFromInt converts a int64 to Decimal.
Example:
NewFromInt(123).String() // output: "123" NewFromInt(-10).String() // output: "-10"
func NewFromInt32 ¶ added in v1.2.1
NewFromInt32 converts a int32 to Decimal.
Example:
NewFromInt(123).String() // output: "123" NewFromInt(-10).String() // output: "-10"
func NewFromString ¶
NewFromString returns a new Decimal from a string representation. Trailing zeroes are not trimmed.
Example:
d, err := NewFromString("-123.45")
d2, err := NewFromString(".0001")
d3, err := NewFromString("1.47000")
func RequireFromString ¶ added in v1.0.1
RequireFromString returns a new Decimal from a string representation or panics if NewFromString would have returned an error.
Example:
d := RequireFromString("-123.45")
d2 := RequireFromString(".0001")
func (Decimal) BigFloat ¶ added in v1.2.1
BigFloat returns decimal as BigFloat. Be aware that casting decimal to BigFloat might cause a loss of precision.
func (Decimal) BigInt ¶ added in v1.2.1
BigInt returns integer component of the decimal as a BigInt.
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) Coefficient ¶
Coefficient returns the coefficient of the decimal. It is scaled by 10^Exponent()
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) DivRound ¶
DivRound divides and rounds to a given precision i.e. to an integer multiple of 10^(-precision)
for a positive quotient digit 5 is rounded up, away from 0 if the quotient is negative then digit 5 is rounded down, away from 0
Note that precision<0 is allowed as input.
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) GobDecode ¶
GobDecode implements the gob.GobDecoder interface for gob serialization.
func (Decimal) GreaterThan ¶
GreaterThan (GT) returns true when d is greater than d2.
func (Decimal) GreaterThanOrEqual ¶
GreaterThanOrEqual (GTE) returns true when d is greater than or equal to d2.
func (Decimal) IsInteger ¶ added in v1.2.1
IsInteger returns true when decimal can be represented as an integer value, otherwise, it returns false.
func (Decimal) IsNegative ¶ added in v1.1.0
IsNegative return
true if d < 0 false if d == 0 false if d > 0
func (Decimal) IsPositive ¶ added in v1.1.0
IsPositive return
true if d > 0 false if d == 0 false if d < 0
func (Decimal) LessThanOrEqual ¶
LessThanOrEqual (LTE) returns true when d is less than or equal to d2.
func (Decimal) MarshalBinary ¶
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (Decimal) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (Decimal) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface for XML serialization.
func (Decimal) QuoRem ¶
QuoRem does divsion with remainder d.QuoRem(d2,precision) returns quotient q and remainder r such that
d = d2 * q + r, q an integer multiple of 10^(-precision) 0 <= r < abs(d2) * 10 ^(-precision) if d>=0 0 >= r > -abs(d2) * 10 ^(-precision) if d<0
Note that precision<0 is allowed as input.
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) RoundBank ¶
RoundBank rounds the decimal to places decimal places. If the final digit to round is equidistant from the nearest two integers the rounded value is taken as the even number
If places < 0, it will round the integer part to the nearest 10^(-places).
Examples:
NewFromFloat(5.45).Round(1).String() // output: "5.4" NewFromFloat(545).Round(-1).String() // output: "540" NewFromFloat(5.46).Round(1).String() // output: "5.5" NewFromFloat(546).Round(-1).String() // output: "550" NewFromFloat(5.55).Round(1).String() // output: "5.6" NewFromFloat(555).Round(-1).String() // output: "560"
func (Decimal) RoundCash ¶
RoundCash aka Cash/Penny/öre rounding rounds decimal to a specific interval. The amount payable for a cash transaction is rounded to the nearest multiple of the minimum currency unit available. The following intervals are available: 5, 10, 25, 50 and 100; any other number throws a panic.
5: 5 cent rounding 3.43 => 3.45 10: 10 cent rounding 3.45 => 3.50 (5 gets rounded up) 25: 25 cent rounding 3.41 => 3.50 50: 50 cent rounding 3.75 => 4.00 100: 100 cent rounding 3.50 => 4.00
For more details: https://en.wikipedia.org/wiki/Cash_rounding
func (Decimal) Shift ¶ added in v1.1.0
Shift shifts the decimal in base 10. It shifts left when shift is positive and right if shift is negative. In simpler terms, the given value for shift is added to the exponent of the decimal.
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) StringFixedBank ¶
StringFixedBank returns a banker rounded fixed-point string with places digits after the decimal point.
Example:
NewFromFloat(0).StringFixedBank(2) // output: "0.00" NewFromFloat(0).StringFixedBank(0) // output: "0" NewFromFloat(5.45).StringFixedBank(0) // output: "5" NewFromFloat(5.45).StringFixedBank(1) // output: "5.4" NewFromFloat(5.45).StringFixedBank(2) // output: "5.45" NewFromFloat(5.45).StringFixedBank(3) // output: "5.450" NewFromFloat(545).StringFixedBank(-1) // output: "540"
func (Decimal) StringFixedCash ¶
StringFixedCash returns a Swedish/Cash rounded fixed-point string. For more details see the documentation at function RoundCash.
func (Decimal) StringScaled ¶
StringScaled first scales the decimal then calls .String() on it. NOTE: buggy, unintuitive, and DEPRECATED! Use StringFixed instead.
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) UnmarshalBinary ¶
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface. As a string representation is already used when encoding to text, this method stores that string as []byte
func (*Decimal) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface.
func (*Decimal) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization.
type NullDecimal ¶
NullDecimal represents a nullable decimal with compatibility for scanning null values from the database.
func (NullDecimal) MarshalJSON ¶
func (d NullDecimal) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface.
func (*NullDecimal) Scan ¶
func (d *NullDecimal) Scan(value interface{}) error
Scan implements the sql.Scanner interface for database deserialization.
func (*NullDecimal) UnmarshalJSON ¶
func (d *NullDecimal) UnmarshalJSON(decimalBytes []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
Source Files