decimal: github.com/shopspring/decimal

## package decimal

`import "github.com/shopspring/decimal"`

Multiprecision decimal numbers. For floating-point formatting only; not general purpose. Only operations are assign and (binary) left/right shift. Can do binary floating point in multiprecision decimal precisely because 2 divides 10; cannot do decimal floating point in multiprecision binary precisely.

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.

Multiprecision decimal numbers. For floating-point formatting only; not general purpose. Only operations are assign and (binary) left/right shift. Can do binary floating point in multiprecision decimal precisely because 2 divides 10; cannot do decimal floating point in multiprecision binary precisely.

### 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.

### type Decimal¶Uses

```type Decimal struct {
// contains filtered or unexported fields
}```

Decimal represents a fixed-point decimal. It is immutable. number = value * 10 ^ exp

#### func Avg¶Uses

`func Avg(first Decimal, rest ...Decimal) Decimal`

Avg returns the average value of the provided first and rest Decimals

#### func Max¶Uses

`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, arr[1:]...)
```

This makes it harder to accidentally call Max with 0 arguments.

#### func Min¶Uses

`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, arr[1:]...)
```

This makes it harder to accidentally call Min with 0 arguments.

#### func New¶Uses

`func New(value int64, exp int32) Decimal`

New returns a new fixed-point decimal, value * 10 ^ exp.

#### func NewFromBigInt¶Uses

`func NewFromBigInt(value *big.Int, exp int32) Decimal`

NewFromBigInt returns a new Decimal from a big.Int, value * 10 ^ exp

#### func NewFromFloat¶Uses

`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

Code:

```fmt.Println(NewFromFloat(123.123123123123).String())
fmt.Println(NewFromFloat(.123123123123123).String())
fmt.Println(NewFromFloat(-1e13).String())```

Output:

```123.123123123123
0.123123123123123
-10000000000000
```

#### func NewFromFloat32¶Uses

`func NewFromFloat32(value float32) Decimal`

NewFromFloat 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

Code:

```fmt.Println(NewFromFloat32(123.123123123123).String())
fmt.Println(NewFromFloat32(.123123123123123).String())
fmt.Println(NewFromFloat32(-1e13).String())```

Output:

```123.12312
0.123123124
-10000000000000
```

#### func NewFromFloatWithExponent¶Uses

`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 NewFromInt¶Uses

`func NewFromInt(value int64) Decimal`

NewFromInt converts a int64 to Decimal.

Example:

```NewFromInt(123).String() // output: "123"
NewFromInt(-10).String() // output: "-10"
```

#### func NewFromInt32¶Uses

`func NewFromInt32(value int32) Decimal`

NewFromInt32 converts a int32 to Decimal.

Example:

```NewFromInt(123).String() // output: "123"
NewFromInt(-10).String() // output: "-10"
```

#### func NewFromString¶Uses

`func NewFromString(value string) (Decimal, error)`

NewFromString returns a new Decimal from a string representation.

Example:

```d, err := NewFromString("-123.45")
d2, err := NewFromString(".0001")
```

#### func RequireFromString¶Uses

`func RequireFromString(value string) Decimal`

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¶Uses

`func Sum(first Decimal, rest ...Decimal) Decimal`

Sum returns the combined total of the provided first and rest Decimals

#### func (Decimal) Abs¶Uses

`func (d Decimal) Abs() Decimal`

Abs returns the absolute value of the decimal.

`func (d Decimal) Add(d2 Decimal) Decimal`

#### func (Decimal) Atan¶Uses

`func (x Decimal) Atan() Decimal`

Atan returns the arctangent, in radians, of x.

#### func (Decimal) Ceil¶Uses

`func (d Decimal) Ceil() Decimal`

Ceil returns the nearest integer value greater than or equal to d.

#### func (Decimal) Cmp¶Uses

`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 (Decimal) Coefficient¶Uses

`func (d Decimal) Coefficient() *big.Int`

Coefficient returns the coefficient of the decimal. It is scaled by 10^Exponent()

#### func (Decimal) Cos¶Uses

`func (d Decimal) Cos() Decimal`

Cos returns the cosine of the radian argument x.

#### func (Decimal) Div¶Uses

`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 (Decimal) DivRound¶Uses

`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 (Decimal) Equal¶Uses

`func (d Decimal) Equal(d2 Decimal) bool`

Equal returns whether the numbers represented by d and d2 are equal.

#### func (Decimal) Equals¶Uses

`func (d Decimal) Equals(d2 Decimal) bool`

#### func (Decimal) Exponent¶Uses

`func (d Decimal) Exponent() int32`

Exponent returns the exponent, or scale component of the decimal.

#### func (Decimal) Float64¶Uses

`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 (Decimal) Floor¶Uses

`func (d Decimal) Floor() Decimal`

Floor returns the nearest integer value less than or equal to d.

#### func (*Decimal) GobDecode¶Uses

`func (d *Decimal) GobDecode(data []byte) error`

GobDecode implements the gob.GobDecoder interface for gob serialization.

#### func (Decimal) GobEncode¶Uses

`func (d Decimal) GobEncode() ([]byte, error)`

GobEncode implements the gob.GobEncoder interface for gob serialization.

#### func (Decimal) GreaterThan¶Uses

`func (d Decimal) GreaterThan(d2 Decimal) bool`

GreaterThan (GT) returns true when d is greater than d2.

#### func (Decimal) GreaterThanOrEqual¶Uses

`func (d Decimal) GreaterThanOrEqual(d2 Decimal) bool`

GreaterThanOrEqual (GTE) returns true when d is greater than or equal to d2.

#### func (Decimal) IntPart¶Uses

`func (d Decimal) IntPart() int64`

IntPart returns the integer component of the decimal.

#### func (Decimal) IsNegative¶Uses

`func (d Decimal) IsNegative() bool`

IsNegative return

```true if d < 0
false if d == 0
false if d > 0
```

#### func (Decimal) IsPositive¶Uses

`func (d Decimal) IsPositive() bool`

IsPositive return

```true if d > 0
false if d == 0
false if d < 0
```

#### func (Decimal) IsZero¶Uses

`func (d Decimal) IsZero() bool`

IsZero return

```true if d == 0
false if d > 0
false if d < 0
```

#### func (Decimal) LessThan¶Uses

`func (d Decimal) LessThan(d2 Decimal) bool`

LessThan (LT) returns true when d is less than d2.

#### func (Decimal) LessThanOrEqual¶Uses

`func (d Decimal) LessThanOrEqual(d2 Decimal) bool`

LessThanOrEqual (LTE) returns true when d is less than or equal to d2.

#### func (Decimal) MarshalBinary¶Uses

`func (d Decimal) MarshalBinary() (data []byte, err error)`

MarshalBinary implements the encoding.BinaryMarshaler interface.

#### func (Decimal) MarshalJSON¶Uses

`func (d Decimal) MarshalJSON() ([]byte, error)`

MarshalJSON implements the json.Marshaler interface.

#### func (Decimal) MarshalText¶Uses

`func (d Decimal) MarshalText() (text []byte, err error)`

MarshalText implements the encoding.TextMarshaler interface for XML serialization.

#### func (Decimal) Mod¶Uses

`func (d Decimal) Mod(d2 Decimal) Decimal`

Mod returns d % d2.

#### func (Decimal) Mul¶Uses

`func (d Decimal) Mul(d2 Decimal) Decimal`

Mul returns d * d2.

#### func (Decimal) Neg¶Uses

`func (d Decimal) Neg() Decimal`

Neg returns -d.

#### func (Decimal) Pow¶Uses

`func (d Decimal) Pow(d2 Decimal) Decimal`

Pow returns d to the power d2

#### func (Decimal) QuoRem¶Uses

`func (d Decimal) QuoRem(d2 Decimal, precision int32) (Decimal, Decimal)`

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) Rat¶Uses

`func (d Decimal) Rat() *big.Rat`

Rat returns a rational number representation of the decimal.

#### func (Decimal) Round¶Uses

`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 (Decimal) RoundBank¶Uses

`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).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¶Uses

`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, 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) Scan¶Uses

`func (d *Decimal) Scan(value interface{}) error`

Scan implements the sql.Scanner interface for database deserialization.

#### func (Decimal) Shift¶Uses

`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 (Decimal) Sign¶Uses

`func (d Decimal) Sign() int`

Sign returns:

```-1 if d <  0
0 if d == 0
+1 if d >  0
```

#### func (Decimal) Sin¶Uses

`func (d Decimal) Sin() Decimal`

Sin returns the sine of the radian argument x.

#### func (Decimal) String¶Uses

`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 (Decimal) StringFixed¶Uses

`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 (Decimal) StringFixedBank¶Uses

`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).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¶Uses

`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 (Decimal) StringScaled¶Uses

`func (d Decimal) StringScaled(exp int32) string`

StringScaled first scales the decimal then calls .String() on it. NOTE: buggy, unintuitive, and DEPRECATED! Use StringFixed instead.

#### func (Decimal) Sub¶Uses

`func (d Decimal) Sub(d2 Decimal) Decimal`

Sub returns d - d2.

#### func (Decimal) Tan¶Uses

`func (d Decimal) Tan() Decimal`

Tan returns the tangent of the radian argument x.

#### func (Decimal) Truncate¶Uses

`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 (*Decimal) UnmarshalBinary¶Uses

`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 (*Decimal) UnmarshalJSON¶Uses

`func (d *Decimal) UnmarshalJSON(decimalBytes []byte) error`

UnmarshalJSON implements the json.Unmarshaler interface.

#### func (*Decimal) UnmarshalText¶Uses

`func (d *Decimal) UnmarshalText(text []byte) error`

UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization.

#### func (Decimal) Value¶Uses

`func (d Decimal) Value() (driver.Value, error)`

Value implements the driver.Valuer interface for database serialization.

### type NullDecimal¶Uses

```type NullDecimal struct {
Decimal Decimal
Valid   bool
}```

NullDecimal represents a nullable decimal with compatibility for scanning null values from the database.

#### func (NullDecimal) MarshalJSON¶Uses

`func (d NullDecimal) MarshalJSON() ([]byte, error)`

MarshalJSON implements the json.Marshaler interface.

#### func (*NullDecimal) Scan¶Uses

`func (d *NullDecimal) Scan(value interface{}) error`

Scan implements the sql.Scanner interface for database deserialization.

#### func (*NullDecimal) UnmarshalJSON¶Uses

`func (d *NullDecimal) UnmarshalJSON(decimalBytes []byte) error`

UnmarshalJSON implements the json.Unmarshaler interface.

#### func (NullDecimal) Value¶Uses

`func (d NullDecimal) Value() (driver.Value, error)`

Value implements the driver.Valuer interface for database serialization.

Package decimal imports 7 packages (graph) and is imported by 1851 packages. Updated 2019-12-14. Refresh now. Tools for package owners.