README
¶
toMath
toMath is a wrapper library for shopspring/decimal, an arbitrary-precision fixed-point decimal numbers in go, where you can create a Decimal, run operations on it, and output the math underlying those operations.
Install
go get github.com/cbelsole/tomath
Requirements
Decimal library requires Go version >=1.7
Usage
package main
import (
"github.com/cbelsole/tomath"
"github.com/stretchr/testify/assert"
)
func main() {
d := tomath.NewFromFloatWithName("var1", 1.1).
Round(1).
Add(tomath.NewFromFloatWithName("var2", 1)).
Add(tomath.NewFromFloatWithName("var2", 1)).
Div(tomath.NewFromFloatWithName("var3", 2)).
Mul(tomath.NewFromFloatWithName("var4", 2)).
SetName("var5")
vars, formula := d.Math()
assert.Equal(t, "(round(1)(var1) + var2 + var2) / var3 * var4 = var5", vars)
assert.Equal(t, "(round(1)(1.1) + 1 + 1) / 2 * 2 = 3.1", formula)
d = d.Resolve().Add(timesOneHundred(tomath.NewFromFloatWithName("var6", 3))).SetName("var7")
vars, formula = d.Math()
assert.Equal(t, "var5 + var6TimesOneHundred = var7", vars)
assert.Equal(t, "3.1 + 300 = 303.1", formula)
}
func timesOneHundred(input tomath.Decimal) tomath.Decimal {
oneHundred := tomath.NewFromFloatWithName("OneHundred", 100)
return input.Mul(oneHundred).ResolveTo(input.GetName() + "Times" + oneHundred.GetName())
}
Notes
- toMath makes no assertions on Decimal names. Use
()+-*/^%=characters at your own risk.
Documentation
pkg.go.dev/github.com/cbelsole/tomath
License
The MIT License (MIT)
shopspring/decimal - The MIT License (MIT)
fpd.Decimal - The MIT License (MIT)
Documentation
¶
Overview ¶
Package tomath wraps github.com/shopspring/decimal library which implements an arbitrary precision fixed-point decimal.
The zero-value of a Decimal is 0, as you would expect. The zero-value name is "?". To set a name for a decimal without a name use the SetName() method.
The best way to create a new Decimal is to use decimal.NewFromStringWithName, ex:
n, err := decimal.NewFromStringWithName("var1", "1.3")
n.String() // output: "3.1"
vars, formula := n.Add("var2", "1.8")
.SetName("var3")
.Math()
// vars: "var1 + var2 = var3"
// formula: "1.3 + 1.8 = 3.1"
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 NewFromBigIntWithName(name string, value *big.Int, exp int32) Decimal
- func NewFromDecimal(d decimal.Decimal) Decimal
- func NewFromDecimalWithName(name string, d decimal.Decimal) Decimal
- func NewFromFloat(value float64) Decimal
- func NewFromFloat32(value float32) Decimal
- func NewFromFloat32WithName(name string, value float32) Decimal
- func NewFromFloatWithExponent(value float64, exp int32) Decimal
- func NewFromFloatWithExponentWithName(name string, value float64, exp int32) Decimal
- func NewFromFloatWithName(name string, value float64) Decimal
- func NewFromInt(value int64) Decimal
- func NewFromInt32(value int32) Decimal
- func NewFromInt32WithName(name string, value int32) Decimal
- func NewFromIntWithName(name string, value int64) Decimal
- func NewFromString(value string) (Decimal, error)
- func NewFromStringWithName(name string, value string) (Decimal, error)
- func NewWithName(name string, value int64, exp int32) Decimal
- func RequireFromString(value string) Decimal
- func RequireFromStringWithName(name string, 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) Decimal() decimal.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) GetName() string
- 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) Math() (string, string)
- 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) Resolve() Decimal
- func (d Decimal) ResolveTo(name string) 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) SetName(name string) Decimal
- func (d Decimal) Shift(s 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
Constants ¶
This section is empty.
Variables ¶
var ( Zero = Decimal{ // contains filtered or unexported fields } )
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 NewFromBigIntWithName ¶
NewFromBigIntWithName returns a new Decimal from a big.Int, value * 10 ^ exp with a given name
func NewFromDecimal ¶
NewFromDecimal returns a new Decimal from github.com/shopspring/decimal#Decimal.
func NewFromDecimalWithName ¶
NewFromDecimalWithName returns a new Decimal from github.com/shopspring/decimal#Decimal with a given name.
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
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
func NewFromFloat32WithName ¶
NewFromFloat32WithName converts a float32 to Decimal with a given name.
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
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 NewFromFloatWithExponentWithName ¶
NewFromFloatWithExponentWithName converts a float64 to Decimal with a given name, with an arbitrary number of fractional digits.
Example:
NewFromFloatWithExponentWithName("var1", 123.456, -2).String() // output: "123.46"
func NewFromFloatWithName ¶
NewFromFloatWithName converts a float64 to Decimal with a given name.
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 NewFromFloatWithNameWithExponent where you can specify the precision in absolute terms.
NOTE: this will panic on NaN, +/-inf
func NewFromInt ¶
NewFromInt converts a int64 to Decimal.
Example:
NewFromInt(123).String() // output: "123" NewFromInt(-10).String() // output: "-10"
func NewFromInt32 ¶
NewFromInt32 converts a int32 to Decimal.
Example:
NewFromInt(123).String() // output: "123" NewFromInt(-10).String() // output: "-10"
func NewFromInt32WithName ¶
NewFromInt32WithName converts a int32 to Decimal with a given name.
Example:
NewFromInt32WithName("var1", 123).String() // output: "123"
NewFromInt32WithName("var1", -10).String() // output: "-10"
func NewFromIntWithName ¶
NewFromIntWithName converts a int64 to Decimal with a given name.
Example:
NewFromIntWithName("var1", 123).String() // output: "123"
NewFromIntWithName("var1", -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 NewFromStringWithName ¶
NewFromStringWithName returns a new Decimal from a string representation with a given name. Trailing zeroes are not trimmed.
Example:
d, err := NewFromStringWithName("var1", "-123.45")
d2, err := NewFromStringWithName("var1", ".0001")
d3, err := NewFromStringWithName("var1", "1.47000")
func NewWithName ¶
NewWithName returns a new fixed-point decimal, value * 10 ^ exp with a given name.
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 RequireFromStringWithName ¶
RequireFromStringWithName returns a new Decimal from a string representation with a given name or panics if NewFromString would have returned an error.
Example:
d := RequireFromStringWithName("var1", "-123.45")
d2 := RequireFromStringWithName("var1", ".0001")
func (Decimal) BigFloat ¶
BigFloat returns decimal as BigFloat. Be aware that casting decimal to BigFloat might cause a loss of precision.
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) Math ¶
Math returns two strings representing the formula underlying the decimal. The first uses the decimal names. The second uses the decimal values. Both are follwed by an equals sign with the current name and value respectively.
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) Resolve ¶
Resolve removes the underlying math from the decimal and replaces it with the current name and value.
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 ¶
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 ¶
type NullDecimal struct {
// contains filtered or unexported fields
}
NullDecimal represents a nullable decimal with compatibility for scanning null values from the database.
func (NullDecimal) Decimal ¶
func (d NullDecimal) Decimal() Decimal
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.
func (NullDecimal) Valid ¶
func (d NullDecimal) Valid() bool
Source Files