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 DivisionPrecision = 16
ExpMaxIterations specifies the maximum number of iterations needed to calculate precise natural exponent value using ExpHullAbrham method.
var ExpMaxIterations = 1000
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 MarshalJSONWithoutQuotes = false
PowPrecisionNegativeExponent specifies the maximum precision of the result (digits after decimal point) when calculating decimal power. Only used for cases where the exponent is a negative number. This constant applies to Pow, PowInt32 and PowBigInt methods, PowWithPrecision method is not constrained by it.
Example:
d1, err := decimal.NewFromFloat(15.2).PowInt32(-2) d1.String() // output: "0.0043282548476454" decimal.PowPrecisionNegativeExponent = 24 d2, err := decimal.NewFromFloat(15.2).PowInt32(-2) d2.String() // output: "0.004328254847645429362881"
var PowPrecisionNegativeExponent = 16
Zero constant, to make computations faster. Zero should never be compared with == or != directly, please use decimal.Equal or decimal.Cmp instead.
var Zero = New(0, 1)
func RescalePair(d1 Decimal, d2 Decimal) (Decimal, Decimal)
RescalePair rescales two decimals to common exponential value (minimal exp of both decimals)
Decimal represents a fixed-point decimal. It is immutable. number = value * 10 ^ exp
type Decimal struct {
// contains filtered or unexported fields
}
func Avg(first Decimal, rest ...Decimal) Decimal
Avg returns the average value of the provided first and rest Decimals
func Max(first Decimal, rest ...Decimal) Decimal
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(first Decimal, rest ...Decimal) Decimal
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 New(value int64, exp int32) Decimal
New returns a new fixed-point decimal, value * 10 ^ exp.
func NewFromBigInt(value *big.Int, exp int32) Decimal
NewFromBigInt returns a new Decimal from a big.Int, value * 10 ^ exp
func NewFromBigRat(value *big.Rat, precision int32) Decimal
NewFromBigRat returns a new Decimal from a big.Rat. The numerator and denominator are divided and rounded to the given precision.
Example:
d1 := NewFromBigRat(big.NewRat(0, 1), 0) // output: "0" d2 := NewFromBigRat(big.NewRat(4, 5), 1) // output: "0.8" d3 := NewFromBigRat(big.NewRat(1000, 3), 3) // output: "333.333" d4 := NewFromBigRat(big.NewRat(2, 7), 4) // output: "0.2857"
func NewFromFloat(value float64) Decimal
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
func NewFromFloat32(value float32) Decimal
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
func NewFromFloatWithExponent(value float64, exp int32) Decimal
NewFromFloatWithExponent converts a float64 to Decimal, with an arbitrary number of fractional digits.
Example:
NewFromFloatWithExponent(123.456, -2).String() // output: "123.46"
func NewFromFormattedString(value string, replRegexp *regexp.Regexp) (Decimal, error)
NewFromFormattedString returns a new Decimal from a formatted string representation. The second argument - replRegexp, is a regular expression that is used to find characters that should be removed from given decimal string representation. All matched characters will be replaced with an empty string.
Example:
r := regexp.MustCompile("[$,]")
d1, err := NewFromFormattedString("$5,125.99", r)
r2 := regexp.MustCompile("[_]")
d2, err := NewFromFormattedString("1_000_000", r2)
r3 := regexp.MustCompile("[USD\\s]")
d3, err := NewFromFormattedString("5000 USD", r3)
func NewFromInt(value int64) Decimal
NewFromInt converts an int64 to Decimal.
Example:
NewFromInt(123).String() // output: "123" NewFromInt(-10).String() // output: "-10"
func NewFromInt32(value int32) Decimal
NewFromInt32 converts an int32 to Decimal.
Example:
NewFromInt(123).String() // output: "123" NewFromInt(-10).String() // output: "-10"
func NewFromString(value string) (Decimal, error)
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 NewFromUint64(value uint64) Decimal
NewFromUint64 converts an uint64 to Decimal.
Example:
NewFromUint64(123).String() // output: "123"
func RequireFromString(value string) Decimal
RequireFromString returns a new Decimal from a string representation or panics if NewFromString had returned an error.
Example:
d := RequireFromString("-123.45")
d2 := RequireFromString(".0001")
func Sum(first Decimal, rest ...Decimal) Decimal
Sum returns the combined total of the provided first and rest Decimals
func (d Decimal) Abs() Decimal
Abs returns the absolute value of the decimal.
func (d Decimal) Add(d2 Decimal) Decimal
Add returns d + d2.
func (d Decimal) Atan() Decimal
Atan returns the arctangent, in radians, of x.
func (d Decimal) BigFloat() *big.Float
BigFloat returns decimal as BigFloat. Be aware that casting decimal to BigFloat might cause a loss of precision.
func (d Decimal) BigInt() *big.Int
BigInt returns integer component of the decimal as a BigInt.
func (d Decimal) Ceil() Decimal
Ceil returns the nearest integer value greater than or equal to d.
func (d Decimal) Cmp(d2 Decimal) int
Cmp compares the numbers represented by d and d2 and returns:
-1 if d < d2 0 if d == d2 +1 if d > d2
func (d Decimal) Coefficient() *big.Int
Coefficient returns the coefficient of the decimal. It is scaled by 10^Exponent()
func (d Decimal) CoefficientInt64() int64
CoefficientInt64 returns the coefficient of the decimal as int64. It is scaled by 10^Exponent() If coefficient cannot be represented in an int64, the result will be undefined.
func (d Decimal) Compare(d2 Decimal) int
Compare compares the numbers represented by d and d2 and returns:
-1 if d < d2 0 if d == d2 +1 if d > d2
func (d Decimal) Copy() Decimal
Copy returns a copy of decimal with the same value and exponent, but a different pointer to value.
func (d Decimal) Cos() Decimal
Cos returns the cosine of the radian argument x.
func (d Decimal) Div(d2 Decimal) Decimal
Div returns d / d2. If it doesn't divide exactly, the result will have DivisionPrecision digits after the decimal point.
func (d Decimal) DivRound(d2 Decimal, precision int32) Decimal
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 (d Decimal) Equal(d2 Decimal) bool
Equal returns whether the numbers represented by d and d2 are equal.
func (d Decimal) Equals(d2 Decimal) bool
Deprecated: Equals is deprecated, please use Equal method instead.
func (d Decimal) ExpHullAbrham(overallPrecision uint32) (Decimal, error)
ExpHullAbrham calculates the natural exponent of decimal (e to the power of d) using Hull-Abraham algorithm. OverallPrecision argument specifies the overall precision of the result (integer part + decimal part).
ExpHullAbrham is faster than ExpTaylor for small precision values, but it is much slower for large precision values.
Example:
NewFromFloat(26.1).ExpHullAbrham(2).String() // output: "220000000000" NewFromFloat(26.1).ExpHullAbrham(20).String() // output: "216314672147.05767284"
func (d Decimal) ExpTaylor(precision int32) (Decimal, error)
ExpTaylor calculates the natural exponent of decimal (e to the power of d) using Taylor series expansion. Precision argument specifies how precise the result must be (number of digits after decimal point). Negative precision is allowed.
ExpTaylor is much faster for large precision values than ExpHullAbrham.
Example:
d, err := NewFromFloat(26.1).ExpTaylor(2).String() d.String() // output: "216314672147.06" NewFromFloat(26.1).ExpTaylor(20).String() d.String() // output: "216314672147.05767284062928674083" NewFromFloat(26.1).ExpTaylor(-10).String() d.String() // output: "220000000000"
func (d Decimal) Exponent() int32
Exponent returns the exponent, or scale component of the decimal.
func (d Decimal) Float64() (f float64, exact bool)
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 (d Decimal) Floor() Decimal
Floor returns the nearest integer value less than or equal to d.
func (d *Decimal) GobDecode(data []byte) error
GobDecode implements the gob.GobDecoder interface for gob serialization.
func (d Decimal) GobEncode() ([]byte, error)
GobEncode implements the gob.GobEncoder interface for gob serialization.
func (d Decimal) GreaterThan(d2 Decimal) bool
GreaterThan (GT) returns true when d is greater than d2.
func (d Decimal) GreaterThanOrEqual(d2 Decimal) bool
GreaterThanOrEqual (GTE) returns true when d is greater than or equal to d2.
func (d Decimal) InexactFloat64() float64
InexactFloat64 returns the nearest float64 value for d. It doesn't indicate if the returned value represents d exactly.
func (d Decimal) IntPart() int64
IntPart returns the integer component of the decimal.
func (d Decimal) IsInteger() bool
IsInteger returns true when decimal can be represented as an integer value, otherwise, it returns false.
func (d Decimal) IsNegative() bool
IsNegative return
true if d < 0 false if d == 0 false if d > 0
func (d Decimal) IsPositive() bool
IsPositive return
true if d > 0 false if d == 0 false if d < 0
func (d Decimal) IsZero() bool
IsZero return
true if d == 0 false if d > 0 false if d < 0
func (d Decimal) LessThan(d2 Decimal) bool
LessThan (LT) returns true when d is less than d2.
func (d Decimal) LessThanOrEqual(d2 Decimal) bool
LessThanOrEqual (LTE) returns true when d is less than or equal to d2.
func (d Decimal) Ln(precision int32) (Decimal, error)
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.
Example:
d1, err := NewFromFloat(13.3).Ln(2) d1.String() // output: "2.59" d2, err := NewFromFloat(579.161).Ln(10) d2.String() // output: "6.3615805046"
func (d Decimal) MarshalBinary() (data []byte, err error)
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (d Decimal) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface.
func (d Decimal) MarshalText() (text []byte, err error)
MarshalText implements the encoding.TextMarshaler interface for XML serialization.
func (d Decimal) Mod(d2 Decimal) Decimal
Mod returns d % d2.
func (d Decimal) Mul(d2 Decimal) Decimal
Mul returns d * d2.
func (d Decimal) Neg() Decimal
Neg returns -d.
func (d Decimal) NumDigits() int
NumDigits returns the number of digits of the decimal coefficient (d.Value)
func (d Decimal) Pow(d2 Decimal) Decimal
Pow returns d to the power of d2. When exponent is negative the returned decimal will have maximum precision of PowPrecisionNegativeExponent places after decimal point.
Pow returns 0 (zero-value of Decimal) instead of error for power operation edge cases, to handle those edge cases use PowWithPrecision Edge cases not handled by Pow:
Example:
d1 := decimal.NewFromFloat(4.0) d2 := decimal.NewFromFloat(4.0) res1 := d1.Pow(d2) res1.String() // output: "256" d3 := decimal.NewFromFloat(5.0) d4 := decimal.NewFromFloat(5.73) res2 := d3.Pow(d4) res2.String() // output: "10118.08037125"
func (d Decimal) PowBigInt(exp *big.Int) (Decimal, error)
PowBigInt returns d to the power of exp, where exp is big.Int. Only returns error when d and exp is 0, thus result is undefined.
When exponent is negative the returned decimal will have maximum precision of PowPrecisionNegativeExponent places after decimal point.
Example:
d1, err := decimal.NewFromFloat(3.0).PowBigInt(big.NewInt(3)) d1.String() // output: "27" d2, err := decimal.NewFromFloat(629.25).PowBigInt(big.NewInt(5)) d2.String() // output: "98654323103449.5673828125"
func (d Decimal) PowInt32(exp int32) (Decimal, error)
PowInt32 returns d to the power of exp, where exp is int32. Only returns error when d and exp is 0, thus result is undefined.
When exponent is negative the returned decimal will have maximum precision of PowPrecisionNegativeExponent places after decimal point.
Example:
d1, err := decimal.NewFromFloat(4.0).PowInt32(4) d1.String() // output: "256" d2, err := decimal.NewFromFloat(3.13).PowInt32(5) d2.String() // output: "300.4150512793"
func (d Decimal) PowWithPrecision(d2 Decimal, precision int32) (Decimal, error)
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.
PowWithPrecision returns error when:
Example:
d1 := decimal.NewFromFloat(4.0) d2 := decimal.NewFromFloat(4.0) res1, err := d1.PowWithPrecision(d2, 2) res1.String() // output: "256" d3 := decimal.NewFromFloat(5.0) d4 := decimal.NewFromFloat(5.73) res2, err := d3.PowWithPrecision(d4, 5) res2.String() // output: "10118.080371595015625" d5 := decimal.NewFromFloat(-3.0) d6 := decimal.NewFromFloat(-6.0) res3, err := d5.PowWithPrecision(d6, 10) res3.String() // output: "0.0013717421"
func (d Decimal) QuoRem(d2 Decimal, precision int32) (Decimal, Decimal)
QuoRem does division 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 (d Decimal) Rat() *big.Rat
Rat returns a rational number representation of the decimal.
func (d Decimal) Round(places int32) Decimal
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 (d Decimal) RoundBank(places int32) Decimal
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 (d Decimal) RoundCash(interval uint8) Decimal
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 (d Decimal) RoundCeil(places int32) Decimal
RoundCeil rounds the decimal towards +infinity.
Example:
NewFromFloat(545).RoundCeil(-2).String() // output: "600" NewFromFloat(500).RoundCeil(-2).String() // output: "500" NewFromFloat(1.1001).RoundCeil(2).String() // output: "1.11" NewFromFloat(-1.454).RoundCeil(1).String() // output: "-1.4"
func (d Decimal) RoundDown(places int32) Decimal
RoundDown rounds the decimal towards zero.
Example:
NewFromFloat(545).RoundDown(-2).String() // output: "500" NewFromFloat(-500).RoundDown(-2).String() // output: "-500" NewFromFloat(1.1001).RoundDown(2).String() // output: "1.1" NewFromFloat(-1.454).RoundDown(1).String() // output: "-1.4"
func (d Decimal) RoundFloor(places int32) Decimal
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 (d Decimal) RoundUp(places int32) Decimal
RoundUp rounds the decimal away from zero.
Example:
NewFromFloat(545).RoundUp(-2).String() // output: "600" NewFromFloat(500).RoundUp(-2).String() // output: "500" NewFromFloat(1.1001).RoundUp(2).String() // output: "1.11" NewFromFloat(-1.454).RoundUp(1).String() // output: "-1.5"
func (d *Decimal) Scan(value interface{}) error
Scan implements the sql.Scanner interface for database deserialization.
func (d Decimal) Shift(shift int32) Decimal
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 (d Decimal) Sign() int
Sign returns:
-1 if d < 0 0 if d == 0 +1 if d > 0
func (d Decimal) Sin() Decimal
Sin returns the sine of the radian argument x.
func (d Decimal) String() 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 (d Decimal) StringFixed(places int32) string
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 (d Decimal) StringFixedBank(places int32) string
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 (d Decimal) StringFixedCash(interval uint8) string
StringFixedCash returns a Swedish/Cash rounded fixed-point string. For more details see the documentation at function RoundCash.
func (d Decimal) StringScaled(exp int32) string
StringScaled first scales the decimal then calls .String() on it.
Deprecated: buggy and unintuitive. Use StringFixed instead.
func (d Decimal) Sub(d2 Decimal) Decimal
Sub returns d - d2.
func (d Decimal) Tan() Decimal
Tan returns the tangent of the radian argument x.
func (d Decimal) Truncate(precision int32) Decimal
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 (d *Decimal) UnmarshalBinary(data []byte) error
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 (d *Decimal) UnmarshalJSON(decimalBytes []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
func (d *Decimal) UnmarshalText(text []byte) error
UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization.
func (d Decimal) Value() (driver.Value, error)
Value implements the driver.Valuer interface for database serialization.
NullDecimal represents a nullable decimal with compatibility for scanning null values from the database.
type NullDecimal struct {
Decimal Decimal
Valid bool
}
func NewNullDecimal(d Decimal) NullDecimal
func (d NullDecimal) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface.
func (d NullDecimal) MarshalText() (text []byte, err error)
MarshalText implements the encoding.TextMarshaler interface for XML serialization.
func (d *NullDecimal) Scan(value interface{}) error
Scan implements the sql.Scanner interface for database deserialization.
func (d *NullDecimal) UnmarshalJSON(decimalBytes []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
func (d *NullDecimal) UnmarshalText(text []byte) error
UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization
func (d NullDecimal) Value() (driver.Value, error)
Value implements the driver.Valuer interface for database serialization.