README
¶
decimal
High performance, zero-allocation, low precision (17 digits), partially compatible with int64 and shopspring Decimal
Features
- the unitialized value is Null and is safe to use without initialization, intepreted as 0 which is different from 0, usefull in omitempty flag for JSON decoding/encoding.
- low-memory usage as internal representation is int64 and value between -144115188075855871 and 144115188075855871 can safely be used as Decimal.
- no heap allocations to prevent garbage collector impact.
- high performance, arithmetic operations are 5x to 150x faster than [shopspring/decimal] package.
- compact binary serialization from 1 to 10 bytes.
- 57 bits mantissa to limit rounding errors compared to float64 (50 bits mantissa) for common operation like additions, multiplications, divisions.
- loss flag available so if a rounding error occurs information is not lost.
- support infinity and NaN decimal as well as near zero value, near negative zero and near positive zero (loss bit always set in such cases).
- since int64 is used internally, Decimal are immutable as no internal pointer are used.
- unique representation for a given decimal, suitable for use as a key in hash table or by using == or != operator directly.
- JSON, XML - compatible with [encoding/json] and [encoding/xml].
- compatible with [shopspring/decimal] except for BigInt and Rat methods not supported.
Install
Run go get github.com/shopspring/decimal
Requirements
Decimal library requires Go version >=1.13.
Documentation
http://godoc.org/github.com/aytechnet/decimal
Usage
Usage taken from [shopspring/decimal] but updated for this package and constant compatibility with int64 :
package main
import (
"fmt"
"github.com/aytechnet/decimal"
)
func main() {
price, err := decimal.NewFromString("136.02")
if err != nil {
panic(err)
}
var quantity decimal.Decimal = 3
fee := decimal.NewFromFloat(.035)
taxRate, _ := decimal.NewFromString(".08875")
subtotal := price.Mul(quantity)
preTax := subtotal.Mul(fee.Add(1))
total := preTax.Mul(taxRate.Add(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
}
Why this package
This package has been created in 2022 and has been used internally for e-commerce related softwares at Aytechnet like DyaPi
or Velonomad. At this time, almost only shopspring/decimal was available.
I would like a decimal package with omitempty friendly interface to encoding/json and a small memory usage.
Since then, much more decimal package alternatives have been made available.
License
The MIT License (MIT)
Some portion of this code inspired directly from shopspring.Decimal, which is also released under the MIT Licence.
Documentation
¶
Index ¶
- Variables
- 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 NewFromBytes(value []byte) (Decimal, error)
- func NewFromFloat(value float64) Decimal
- func NewFromFloat32(value float32) Decimal
- func NewFromFloat64Exact(value float64, exact bool) 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 NewFromUint64(value uint64) Decimal
- func RequireFromString(value string) Decimal
- func Sum(first Decimal, rest ...Decimal) Decimal
- func (d Decimal) Abs() Decimal
- func (d1 Decimal) Add(d2 Decimal) Decimal
- func (d Decimal) Atan() Decimal
- func (d Decimal) Bytes() (b []byte)
- func (d Decimal) Ceil() Decimal
- func (d1 Decimal) Cmp(d2 Decimal) int
- func (d1 Decimal) Compare(d2 Decimal) int
- func (d Decimal) Cos() Decimal
- func (d1 Decimal) Div(d2 Decimal) Decimal
- func (d1 Decimal) Equal(d2 Decimal) bool
- 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 (d1 Decimal) GreatherThan(d2 Decimal) bool
- func (d1 Decimal) GreatherThanOrEqual(d2 Decimal) bool
- func (d Decimal) IfNull(default_value Decimal) Decimal
- func (d Decimal) InexactFloat64() float64
- func (d Decimal) Int64() (i int64)
- func (d Decimal) IntPart() (i int64)
- func (d Decimal) IntPartErr() (int64, error)
- func (d Decimal) IsExact() bool
- func (d Decimal) IsExactlyZero() bool
- func (d Decimal) IsInfinite() bool
- func (d Decimal) IsInteger() bool
- func (d Decimal) IsNaN() bool
- func (d Decimal) IsNegative() bool
- func (d Decimal) IsNull() bool
- func (d Decimal) IsPositive() bool
- func (d Decimal) IsSet() bool
- func (d Decimal) IsZero() bool
- func (d1 Decimal) LessThan(d2 Decimal) bool
- func (d1 Decimal) LessThanOrEqual(d2 Decimal) bool
- func (d Decimal) Ln(precision int32) Decimal
- func (d Decimal) MarshalBinary() (data []byte, err error)
- func (d Decimal) MarshalJSON() ([]byte, error)
- func (d Decimal) MarshalText() (text []byte, err error)
- func (d1 Decimal) Mod(d2 Decimal) Decimal
- func (d1 Decimal) Mul(d2 Decimal) Decimal
- func (d Decimal) Neg() Decimal
- func (d1 Decimal) Pow(d2 Decimal) Decimal
- func (d1 Decimal) PowWithPrecision(d2 Decimal, precision int32) (Decimal, error)
- func (d1 Decimal) QuoRem(d2 Decimal, precision int32) (Decimal, Decimal)
- func (d Decimal) Round(places int32) Decimal
- func (d Decimal) RoundBank(places int32) Decimal
- func (d Decimal) RoundCeil(places int32) Decimal
- func (d Decimal) RoundFloor(places int32) Decimal
- func (d *Decimal) Scan(value interface{}) (err error)
- func (d Decimal) Sign() int
- func (d Decimal) Sin() Decimal
- func (d Decimal) Sqrt() Decimal
- func (d Decimal) String() string
- func (d1 Decimal) Sub(d2 Decimal) Decimal
- func (d Decimal) Tan() Decimal
- func (d *Decimal) UnmarshalBinary(data []byte) error
- func (d *Decimal) UnmarshalJSON(b []byte) error
- func (d *Decimal) UnmarshalText(text []byte) error
- func (d Decimal) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrOutOfRange can occurs when converting a decimal to a int or int64 as integer may not hold the integer part of the decimal value. ErrOutOfRange = errors.New("out of range") // ErrSyntax can occurs when converting a string to a decimal. ErrSyntax = errors.New("invalid syntax") // ErrFormatcan occurs when decoding a binary to a decimal. ErrFormat = errors.New("invalid format") // DivisionPrecision has the number of decimal places in the result when it doesn't divide exactly. DivisionPrecision = 16 )
Functions ¶
This section is empty.
Types ¶
type Decimal ¶
type Decimal int64
Decimal represents a fixed-point decimal hold as a 64 bits integer integer value between -144115188075855871 and 144115188075855871 (or MaxInt) can safely be used as Decimal, example :
var a Decimal = -1001 // a is a Decimal of integer value -1001
if a.Div(1000).Sub(1).Div(5).Mul(14000).Add(14).Div(-28) == 1000 {
fmt.Printf("ok: (((a/1000)-1)*14000+14)/-28 == 1000\n") // will print "ok: (((a/1000)-1)*14000+14)/-28 == 1000"
}
Note 0 is unitialized Decimal and its value for calculation is 0 like Zero which is initialized 0 Note Zero is now the same int64 value as types.IntZero, so casting an types.IntZero to Decimal is safe provided is absolute value is not too high Note you need to use Decimal method for calculation, you cannot use + - * / or any other operators unless Decimal is a real non-zero integer value Unitialized Decimal is usefull when using JSON marshaling/unmarshaling.
Note Decimal does not follow IEEE 754 decimal floating point 64 bits representation. This is because Decimal is compatible with a large range of int64 values as described above for ease of use and use extended mantissa of 57 bits instead of 50 bits for IEEE 754 decimal floating point, thus providing only 17 significant digits (in fact a little more than float64)
const ( // Null constant is the default value of a decimal left unitialized. // A decimal can be directly initialized with 0 and it will be empty. // Null can be safely compared with == or != directly, you may use decimal.IsNull or any other decimal method to check if it is null. // Any operation on Decimal will never return a Null. // Null is seen as 0 for any operation Null = 0 // MaxInt constant is the maximal int64 value that can be safely saved as Decimal with exposant still 0. // MaxInt is as well the maximum value of mantissa of Decimal and the bitmask to extract mantissa value of a Decimal. MaxInt = 0x01ffffffffffffff // Zero constant is not empty zero Decimal value. // A decimal can be directly initialized with Zero and it will be not empty, but zero. // Zero can be safely compared with == or != directly to check for not empty zero decimal value. // But you need to use d.IsExactlyZero() to test if decimal d is zero or null. Zero Decimal = math.MinInt64 // NearZero represents a decimal value too close to 0 but not equal to zero, its sign is undefined. // NearPositiveZero and NearNegativeZero represents a signed decimal value too close to 0 but not equal to zero, its sign has been kept. // They can be safely compared with == or != directly but -NearZero may occurs and should be "seen" as NearZero NearZero Decimal = Zero | loss NearPositiveZero Decimal = 0x6000000000000000 NearNegativeZero Decimal = -NearPositiveZero // PositiveInfinity and NegativeInfinity are constants that represents decimal too big to be represented as a decimal value. // They can safely be compared with == or != directly to check for infinite value. PositiveInfinity Decimal = 0x5e00000000000000 NegativeInfinity Decimal = -PositiveInfinity // NaN represent a decimal wich do not represents any more a number. // NaN should never be compared with == or != directly as they are multiple representation of such "nan" internally (search for NaN boxing for more info). // Use IsNaN method to check if a decimal is not a number. NaN Decimal = 0x4200000000000000 )
func New ¶
New returns a new fixed-point decimal, value * 10 ^ exp, compatible with shopspring/decimal New function.
func NewFromBytes ¶
NewFromBytes returns a new Decimal from a slice of bytes representation.
func NewFromFloat ¶
NewFromFloat converts a float64 to Decimal.
func NewFromFloat32 ¶
NewFromFloat32 converts a float32 to Decimal.
func NewFromFloat64Exact ¶
NewFromFloat converts a float64 to Decimal.
func NewFromFloatWithExponent ¶
NewFromFloatWithExponent converts a float64 to Decimal, with an arbitrary number of fractional digits.
func NewFromInt32 ¶
NewFromInt32 converts a int32 to Decimal.
func NewFromString ¶
NewFromString returns a new Decimal from a string representation.
Example:
d, err := NewFromString("-123.45")
d2, err := NewFromString(".0001")
d3, err := NewFromString("1.47000")
d4, err := NewFromString("3.14e15")
func NewFromUint64 ¶
NewFromUint64 converts uint64 to Decimal.
func RequireFromString ¶
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 Sum ¶
Sum returns the combined total of the provided first and rest Decimals using improved Kahan–Babuška Neumaier algorithm, see https://en.wikipedia.org/wiki/Kahan_summation_algorithm
Example:
d := Sum(1, RequireFromString("1e30"), 1, RequireFromString("-1e30"))
func (Decimal) Bytes ¶
Bytes returns the string representation of the decimal as a slice of byte, but nil if the decimal is Null.
func (Decimal) Compare ¶
Compare compares the numbers represented by d1 and d2 and returns:
-1 if d1 < d2 0 if d1 == d2 +1 if d1 > d2
func (Decimal) Div ¶
Div returns d1 / d2. If it doesn't divide exactly, the result will have DivisionPrecision digits after the decimal point and loss bit will be set.
func (Decimal) Equal ¶
Equal returns whether d1 == d2 without taking care of loss bit. The values Null, Zero, NearZero, NearPositiveZero and NearNegativeZero are equals.
func (Decimal) Float64 ¶
Float64 returns the nearest float64 value for d and a bool indicating whether f may represents d exactly.
func (*Decimal) GobDecode ¶
GobDecode implements the gob.GobDecoder interface for gob serialization.
func (Decimal) GreatherThan ¶
GreaterThan returns true when d1 is greater than d2 (d1 > d2).
func (Decimal) GreatherThanOrEqual ¶
GreaterThanOrEqual returns true when d1 is greater than or equal to d2 (d1 >= d2).
func (Decimal) InexactFloat64 ¶
InexactFloat64 returns the nearest float64 value for d.
func (Decimal) Int64 ¶
Int64 returns the integer component of the decimal, this method is a synonym of IntPart
func (Decimal) IntPartErr ¶
IntPartErr return the integer component of the decimal and an eventual out-of-range error of conversion.
func (Decimal) IsExact ¶
IsExact return true if a decimal has its loss bit not set, ie it has not lost its precision during computation or conversion.
func (Decimal) IsExactlyZero ¶
IsExactlyZero return
true if d == Null or d == Zero false if d == ~0 or d == -~0 or d == +~0 false if d < 0 false if d > 0
func (Decimal) IsInfinite ¶
IsInfinite return
true if a d == +Inf or d == -Inf false in any other case
func (Decimal) IsNaN ¶
IsNaN return
true if a decimal is not a a number (NaN) or infinity (+Inf or -Inf) false in any other case
func (Decimal) IsNegative ¶
IsNegative return
true if d < 0 or d == ~-0 false if d == Null or d == Zero or d == ~0 false if d > 0
func (Decimal) IsNull ¶
IsNull return
true if d == Null false if d == 0 false if d == ~0 or d == -~0 or d == +~0 false if d < 0 false if d > 0
func (Decimal) IsPositive ¶
IsPositive return
true if d > 0 or d == ~+0 false if d == Null or d == Zero or d == ~0 false if d < 0 or d == ~-0
func (Decimal) IsSet ¶
IsSet return
false if d == Null true if d == 0 true if d == ~0 or d == -~0 or d == +~0 true if d < 0 true if d > 0
func (Decimal) IsZero ¶
IsZero return
true if d == Null or d == Zero true if d == ~0 or d == -~0 or d == +~0 false if d < 0 false if d > 0
func (Decimal) LessThanOrEqual ¶
LessThanOrEqual returns true when d1 is less than or equal to d2 (d1 <= d2).
func (Decimal) Ln ¶
Ln calculates natural logarithm of d. Precision argument specifies how precise the result must be (number of digits after decimal point). Negative precision is allowed.
func (Decimal) MarshalBinary ¶
MarshalJSON implements the json.Marshaler interface.
func (Decimal) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (Decimal) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface for XML serialization.
func (Decimal) PowWithPrecision ¶
PowWithPrecision returns d to the power of d2. Precision parameter specifies minimum precision of the result (digits after decimal point). Returned decimal is not rounded to 'precision' places after decimal point.
func (Decimal) QuoRem ¶
QuoRem does division with remainder d1.QuoRem(d2,precision) returns quotient q and remainder r such that
d1 = d2 * q + r, q an integer multiple of 10^(-precision) 0 <= r < abs(d2) * 10 ^(-precision) if d1 >= 0 0 >= r > -abs(d2) * 10 ^(-precision) if d1 < 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).
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).RoundBank(1).String() // output: "5.4" NewFromFloat(545).RoundBank(-1).String() // output: "540" NewFromFloat(5.46).RoundBank(1).String() // output: "5.5" NewFromFloat(546).RoundBank(-1).String() // output: "550" NewFromFloat(5.55).RoundBank(1).String() // output: "5.6" NewFromFloat(555).RoundBank(-1).String() // output: "560"
func (Decimal) RoundFloor ¶
RoundFloor rounds the decimal towards -infinity.
Example:
NewFromFloat(545).RoundFloor(-2).String() // output: "500" NewFromFloat(-500).RoundFloor(-2).String() // output: "-500" NewFromFloat(1.1001).RoundFloor(2).String() // output: "1.1" NewFromFloat(-1.454).RoundFloor(1).String() // output: "-1.5"
func (Decimal) Sign ¶
Sign return
0 if d == Null or d == Zero or d == ~0 1 if d > 0 or d == ~+0 -1 if d < 0 or d == ~-0 undefined (1 or -1) if d is NaN
func (Decimal) Sqrt ¶
Sqrt computes the (possibly rounded) square root of a decimal.
Special cases are:
Sqrt(+Inf) = +Inf Sqrt(±0) = ±0 Sqrt(x < 0) = NaN Sqrt(NaN) = NaN
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) UnmarshalBinary ¶
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
func (*Decimal) UnmarshalJSON ¶
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
func (*Decimal) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization.
Source Files