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 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 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) 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) 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) Rescale(exp int32) Decimal
- 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 ErrorExponentLimit
- type ErrorInvalidFormat
- type ErrorInvalidType
- type NullDecimal
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( Zero = New(0, 0) One = New(1, 0) Two = New(2, 0) Five = New(5, 0) Ten = New(1, 1) )
Common decimal constants, to make computations faster.
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.
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 ¶
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 ¶
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 NewFromString ¶
NewFromString returns a new Decimal from a string representation.
Example:
d, err := NewFromString("-123.45") d2, err := NewFromString(".0001")
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 (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) 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) Rescale ¶
Rescale returns a rescaled version of the decimal. Returned decimal may be less precise if the given exponent is bigger than the initial exponent of the Decimal. NOTE: this will truncate, NOT round
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, 15, 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) 15: 10 cent rounding 3.45 => 3.40 (5 gets rounded down) 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 ¶
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).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.4" NewFromFloat(5.45).StringFixed(2) // output: "5.45" NewFromFloat(5.45).StringFixed(3) // output: "5.450" NewFromFloat(545).StringFixed(-1) // output: "550"
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 ErrorExponentLimit ¶
type ErrorExponentLimit struct {
// contains filtered or unexported fields
}
ErrorExponentLimit is returned when the decimal exponent exceed int32 range.
func (*ErrorExponentLimit) Error ¶
func (e *ErrorExponentLimit) Error() string
Error implements error interface.
type ErrorInvalidFormat ¶
type ErrorInvalidFormat struct {
// contains filtered or unexported fields
}
ErrorInvalidFormat is returned when the input string is not valid integer.
func (*ErrorInvalidFormat) Error ¶
func (e *ErrorInvalidFormat) Error() string
Error implements error interface.
type ErrorInvalidType ¶
type ErrorInvalidType struct {
// contains filtered or unexported fields
}
ErrorInvalidType is returned when the value passed into sql.Scanner is not with expected type. (valid types: int64, float64, []byte, string)
func (*ErrorInvalidType) Error ¶
func (e *ErrorInvalidType) Error() string
Error implements error interface.
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.