# decimal

package module
v1.4.0 Latest Latest

Go to latest
Published: Apr 12, 2024 License: MIT

### decimal

Arbitrary-precision fixed-point decimal numbers in go.

Note: Decimal library can "only" represent numbers with a maximum of 2^31 digits after the decimal point.

#### Features

• The zero-value is 0, and is safe to use without initialization
• Addition, subtraction, multiplication with no loss of precision
• Division with specified precision
• Database/sql serialization/deserialization
• JSON and XML serialization/deserialization

#### Install

Run `go get github.com/shopspring/decimal`

#### Requirements

Decimal library requires Go version `>=1.10`

#### Documentation

http://godoc.org/github.com/shopspring/decimal

#### Usage

``````package main

import (
"fmt"
"github.com/shopspring/decimal"
)

func main() {
price, err := decimal.NewFromString("136.02")
if err != nil {
panic(err)
}

quantity := decimal.NewFromInt(3)

fee, _ := decimal.NewFromString(".035")
taxRate, _ := decimal.NewFromString(".08875")

subtotal := price.Mul(quantity)

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
}
``````

#### Alternative libraries

When working with decimal numbers, you might face problems this library is not perfectly suited for. Fortunately, thanks to the wonderful community we have a dozen other libraries that you can choose from.
Explore other alternatives to find the one that best fits your needs :)

• cockroachdb/apd - arbitrary precision, mutable and rich API similar to `big.Int`, more performant than this library
• alpacahq/alpacadecimal - high performance, low precision (12 digits), fully compatible API with this library
• govalues/decimal - high performance, zero-allocation, low precision (19 digits)
• greatcloak/decimal - fork focusing on billing and e-commerce web application related use cases, includes out-of-the-box BSON marshaling support

#### FAQ

###### Why don't you just use float64?

Because float64 (or any binary floating point type, actually) can't represent numbers such as `0.1` exactly.

Consider this code: http://play.golang.org/p/TQBd4yJe6B You might expect that it prints out `10`, but it actually prints `9.999999999999831`. Over time, these small errors can really add up!

###### Why don't you just use big.Rat?

big.Rat is fine for representing rational numbers, but Decimal is better for representing money. Why? Here's a (contrived) example:

Let's say you use big.Rat, and you have two numbers, x and y, both representing 1/3, and you have `z = 1 - x - y = 1/3`. If you print each one out, the string output has to stop somewhere (let's say it stops at 3 decimal digits, for simplicity), so you'll get 0.333, 0.333, and 0.333. But where did the other 0.001 go?

Here's the above example as code: http://play.golang.org/p/lCZZs0w9KE

With Decimal, the strings being printed out represent the number exactly. So, if you have `x = y = 1/3` (with precision 3), they will actually be equal to 0.333, and when you do `z = 1 - x - y`, `z` will be equal to .334. No money is unaccounted for!

You still have to be careful. If you want to split a number `N` 3 ways, you can't just send `N/3` to three different people. You have to pick one to send `N - (2/3*N)` to. That person will receive the fraction of a penny remainder.

But, it is much easier to be careful with Decimal than with big.Rat.

###### Why isn't the API similar to big.Int's?

big.Int's API is built to reduce the number of memory allocations for maximal performance. This makes sense for its use-case, but the trade-off is that the API is awkward and easy to misuse.

For example, to add two big.Ints, you do: `z := new(big.Int).Add(x, y)`. A developer unfamiliar with this API might try to do `z := a.Add(a, b)`. This modifies `a` and sets `z` as an alias for `a`, which they might not expect. It also modifies any other aliases to `a`.

Here's an example of the subtle bugs you can introduce with big.Int's API: https://play.golang.org/p/x2R_78pa8r

In contrast, it's difficult to make such mistakes with decimal. Decimals behave like other go numbers types: even though `a = b` will not deep copy `b` into `a`, it is impossible to modify a Decimal, since all Decimal methods return new Decimals and do not modify the originals. The downside is that this causes extra allocations, so Decimal is less performant. My assumption is that if you're using Decimals, you probably care more about correctness than performance.

This is a heavily modified fork of fpd.Decimal, which was also released under the MIT License.

## Documentation ¶

### Overview ¶

Package decimal implements an arbitrary precision fixed-point 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"
```

To use Decimal as part of a struct:

```type StructName struct {
Number Decimal
}
```

Note: This can "only" represent numbers with a maximum of 2^31 digits after the decimal point.

### Constants ¶

This section is empty.

### Variables ¶

View Source
`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"
```
View Source
`var ExpMaxIterations = 1000`

ExpMaxIterations specifies the maximum number of iterations needed to calculate precise natural exponent value using ExpHullAbrham method.

View Source
`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.

View Source
`var PowPrecisionNegativeExponent = 16`

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"
```
View Source
`var Zero = New(0, 1)`

Zero constant, to make computations faster. Zero should never be compared with == or != directly, please use decimal.Equal or decimal.Cmp instead.

### Functions ¶

#### func RescalePair ¶ added in v1.2.0

`func RescalePair(d1 Decimal, d2 Decimal) (Decimal, Decimal)`

RescalePair rescales two decimals to common exponential value (minimal exp of both decimals)

### 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 Avg ¶

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

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

#### func Max ¶

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

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

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

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

#### func NewFromBigInt ¶

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

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

#### func NewFromBigRat ¶ added in v1.4.0

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

`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
```fmt.Println(NewFromFloat(123.123123123123).String())
fmt.Println(NewFromFloat(.123123123123123).String())
fmt.Println(NewFromFloat(-1e13).String())
```
```Output:

123.123123123123
0.123123123123123
-10000000000000
```

#### func NewFromFloat32 ¶ added in v1.1.0

`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
```fmt.Println(NewFromFloat32(123.123123123123).String())
fmt.Println(NewFromFloat32(.123123123123123).String())
fmt.Println(NewFromFloat32(-1e13).String())
```
```Output:

123.12312
0.123123124
-10000000000000
```

#### func NewFromFloatWithExponent ¶

`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 ¶ added in v1.3.0

`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 ¶ added in v1.2.0

`func NewFromInt(value int64) Decimal`

NewFromInt converts an int64 to Decimal.

Example:

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

#### func NewFromInt32 ¶ added in v1.2.0

`func NewFromInt32(value int32) Decimal`

NewFromInt32 converts an int32 to Decimal.

Example:

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

#### func NewFromString ¶

`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 ¶ added in v1.4.0

`func NewFromUint64(value uint64) Decimal`

NewFromUint64 converts an uint64 to Decimal.

Example:

```NewFromUint64(123).String() // output: "123"
```

#### func RequireFromString ¶ added in v1.0.1

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

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

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

#### func (Decimal) Abs ¶

`func (d Decimal) Abs() Decimal`

Abs returns the absolute value of the decimal.

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

#### func (Decimal) Atan ¶ added in v1.1.0

`func (d Decimal) Atan() Decimal`

Atan returns the arctangent, in radians, of x.

#### func (Decimal) BigFloat ¶ added in v1.2.0

`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 (Decimal) BigInt ¶ added in v1.2.0

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

BigInt returns integer component of the decimal as a BigInt.

#### func (Decimal) Ceil ¶

`func (d Decimal) Ceil() Decimal`

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

#### func (Decimal) Cmp ¶

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

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

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

#### func (Decimal) CoefficientInt64 ¶ added in v1.3.0

`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 (Decimal) Compare ¶ added in v1.4.0

`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 (Decimal) Copy ¶ added in v1.3.0

`func (d Decimal) Copy() Decimal`

Copy returns a copy of decimal with the same value and exponent, but a different pointer to value.

#### func (Decimal) Cos ¶ added in v1.1.0

`func (d Decimal) Cos() Decimal`

Cos returns the cosine of the radian argument x.

#### func (Decimal) Div ¶

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

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

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

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

#### func (Decimal) Equals deprecated

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

#### func (Decimal) ExpHullAbrham ¶ added in v1.3.0

`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 (Decimal) ExpTaylor ¶ added in v1.3.0

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

`func (d Decimal) Exponent() int32`

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

#### func (Decimal) Float64 ¶

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

`func (d Decimal) Floor() Decimal`

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

#### func (*Decimal) GobDecode ¶

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

GobDecode implements the gob.GobDecoder interface for gob serialization.

#### func (Decimal) GobEncode ¶

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

GobEncode implements the gob.GobEncoder interface for gob serialization.

#### func (Decimal) GreaterThan ¶

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

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

#### func (Decimal) GreaterThanOrEqual ¶

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

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

#### func (Decimal) InexactFloat64 ¶ added in v1.3.0

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

`func (d Decimal) IntPart() int64`

IntPart returns the integer component of the decimal.

#### func (Decimal) IsInteger ¶ added in v1.3.0

`func (d Decimal) IsInteger() bool`

IsInteger returns true when decimal can be represented as an integer value, otherwise, it returns false.

#### func (Decimal) IsNegative ¶ added in v1.1.0

`func (d Decimal) IsNegative() bool`

IsNegative return

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

#### func (Decimal) IsPositive ¶ added in v1.1.0

`func (d Decimal) IsPositive() bool`

IsPositive return

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

#### func (Decimal) IsZero ¶ added in v1.1.0

`func (d Decimal) IsZero() bool`

IsZero return

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

#### func (Decimal) LessThan ¶

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

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

#### func (Decimal) LessThanOrEqual ¶

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

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

#### func (Decimal) Ln ¶ added in v1.4.0

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

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

MarshalBinary implements the encoding.BinaryMarshaler interface.

#### func (Decimal) MarshalJSON ¶

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

MarshalJSON implements the json.Marshaler interface.

#### func (Decimal) MarshalText ¶

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

MarshalText implements the encoding.TextMarshaler interface for XML serialization.

#### func (Decimal) Mod ¶

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

Mod returns d % d2.

#### func (Decimal) Mul ¶

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

Mul returns d * d2.

#### func (Decimal) Neg ¶

`func (d Decimal) Neg() Decimal`

Neg returns -d.

#### func (Decimal) NumDigits ¶ added in v1.3.0

`func (d Decimal) NumDigits() int`

NumDigits returns the number of digits of the decimal coefficient (d.Value)

#### func (Decimal) Pow ¶

`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:

• 0 ** 0 => undefined value
• 0 ** y, where y < 0 => infinity
• x ** y, where x < 0 and y is non-integer decimal => imaginary value

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 (Decimal) PowBigInt ¶ added in v1.4.0

`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 (Decimal) PowInt32 ¶ added in v1.4.0

`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 (Decimal) PowWithPrecision ¶ added in v1.4.0

`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:

• 0 ** 0 => undefined value
• 0 ** y, where y < 0 => infinity
• x ** y, where x < 0 and y is non-integer decimal => imaginary value

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 (Decimal) QuoRem ¶

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

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

Rat returns a rational number representation of the decimal.

#### func (Decimal) Round ¶

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

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

`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 (Decimal) RoundCeil ¶ added in v1.3.0

`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 (Decimal) RoundDown ¶ added in v1.3.0

`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 (Decimal) RoundFloor ¶ added in v1.3.0

`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 (Decimal) RoundUp ¶ added in v1.3.0

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

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

Scan implements the sql.Scanner interface for database deserialization.

#### func (Decimal) Shift ¶ added in v1.1.0

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

`func (d Decimal) Sign() int`

Sign returns:

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

#### func (Decimal) Sin ¶ added in v1.1.0

`func (d Decimal) Sin() Decimal`

Sin returns the sine of the radian argument x.

#### func (Decimal) String ¶

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

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

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

`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 deprecated

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

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

Sub returns d - d2.

#### func (Decimal) Tan ¶ added in v1.1.0

`func (d Decimal) Tan() Decimal`

Tan returns the tangent of the radian argument x.

#### func (Decimal) Truncate ¶

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

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

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

UnmarshalJSON implements the json.Unmarshaler interface.

#### func (*Decimal) UnmarshalText ¶

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

UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization.

#### func (Decimal) Value ¶

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

Value implements the driver.Valuer interface for database serialization.

#### type NullDecimal ¶

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

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

#### func NewNullDecimal ¶ added in v1.3.0

`func NewNullDecimal(d Decimal) NullDecimal`

#### func (NullDecimal) MarshalJSON ¶

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

MarshalJSON implements the json.Marshaler interface.

#### func (NullDecimal) MarshalText ¶ added in v1.3.0

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

MarshalText implements the encoding.TextMarshaler interface for XML serialization.

#### 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) UnmarshalText ¶ added in v1.3.0

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

UnmarshalText implements the encoding.TextUnmarshaler interface for XML deserialization

#### func (NullDecimal) Value ¶

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

Value implements the driver.Valuer interface for database serialization.