Documentation
¶
Overview ¶
Package dec implements multi-precision decimal arithmetic. It supports the numeric type Dec for signed decimals. It is based on and complements the multi-precision integer implementation (Int) in the Go library (math/big).
Methods are typically of the form:
func (z *Dec) Op(x, y *Dec) *Dec
and implement operations z = x Op y with the result as receiver; if it is one of the operands it may be overwritten (and its memory reused). To enable chaining of operations, the result is also returned. Methods returning a result other than *Dec take one of the operands as the receiver.
Quotient (division) operation uses Scalers and Rounders to specify the desired behavior. See Quo, Scaler, and Rounder for details.
Index ¶
- type Dec
- func (z *Dec) Abs(x *Dec) *Dec
- func (z *Dec) Add(x, y *Dec) *Dec
- func (x *Dec) Cmp(y *Dec) int
- func (x *Dec) Format(s fmt.State, ch rune)
- func (z *Dec) GobDecode(buf []byte) error
- func (x *Dec) GobEncode() ([]byte, error)
- func (z *Dec) Mul(x, y *Dec) *Dec
- func (z *Dec) Neg(x *Dec) *Dec
- func (z *Dec) Quo(x, y *Dec, scaler Scaler, rounder Rounder) *Dec
- func (z *Dec) QuoExact(x, y *Dec) *Dec
- func (z *Dec) Round(x *Dec, s Scale, r Rounder) *Dec
- func (x *Dec) Scale() Scale
- func (z *Dec) Scan(s fmt.ScanState, ch rune) error
- func (z *Dec) Set(x *Dec) *Dec
- func (x *Dec) SetScale(scale Scale) *Dec
- func (z *Dec) SetString(s string) (*Dec, bool)
- func (x *Dec) SetUnscaled(unscaled *big.Int) *Dec
- func (x *Dec) Sign() int
- func (x *Dec) String() string
- func (z *Dec) Sub(x, y *Dec) *Dec
- func (x *Dec) Unscaled() *big.Int
- type Rounder
- type Scale
- type Scaler
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dec ¶
type Dec struct {
// contains filtered or unexported fields
}
A Dec represents a signed multi-precision decimal. It is stored as a combination of a multi-precision big.Int unscaled value and a fixed-precision scale of type Scale.
The mathematical value of a Dec equals:
unscaled * 10**(-scale)
Note that different Dec representations may have equal mathematical values.
unscaled scale String()
-------------------------
0 0 "0"
0 2 "0.00"
0 -2 "0"
1 0 "1"
100 2 "1.00"
10 0 "10"
1 -1 "10"
The zero value for a Dec represents the value 0 with scale 0.
func NewDecInt64 ¶
NewDecInt64 allocates and returns a new Dec set to the given int64 value with scale 0.
func (*Dec) Add ¶
Add sets z to the sum x+y and returns z. The scale of z is the greater of the scales of x and y.
func (*Dec) Format ¶
Format is a support routine for fmt.Formatter. It accepts the decimal formats 'd' and 'f', and handles both equivalently. Width, precision, flags and bases 2, 8, 16 are not supported.
func (*Dec) Mul ¶
Mul sets z to the product x*y and returns z. The scale of z is the sum of the scales of x and y.
func (*Dec) Quo ¶
Quo sets z to the quotient x/y, with the scale obtained from the given Scaler, rounded using the given Rounder. If the result from the rounder is nil, Quo also returns nil, and the value of z is undefined.
There is no corresponding Div method; the equivalent can be achieved through the choice of Rounder used.
See Rounder for details on the various ways for rounding.
Example (Scale2RoundCeil) ¶
package main
import (
"fmt"
"code.google.com/p/godec/dec"
)
func main() {
// -42 / 400 is an finite decimal with 3 digits beyond the decimal point
x, y := dec.NewDecInt64(-42), dec.NewDecInt64(400)
// use 2 digits beyond decimal point, round towards positive infinity
z := new(dec.Dec).Quo(x, y, dec.Scale(2), dec.RoundCeil)
fmt.Println(z)
}
Output: -0.10
Example (Scale2RoundDown) ¶
package main
import (
"fmt"
"code.google.com/p/godec/dec"
)
func main() {
// 10 / 3 is an infinite decimal; it has no exact Dec representation
x, y := dec.NewDecInt64(10), dec.NewDecInt64(3)
// use 2 digits beyond the decimal point, round towards 0
z := new(dec.Dec).Quo(x, y, dec.Scale(2), dec.RoundDown)
fmt.Println(z)
}
Output: 3.33
func (*Dec) QuoExact ¶
QuoExact(x, y) is a shorthand for Quo(x, y, ScaleQuoExact, RoundExact). If x/y can be expressed as a Dec without rounding, QuoExact sets z to the quotient x/y and returns z. Otherwise, it returns nil and the value of z is undefined.
Example (Fail) ¶
package main
import (
"fmt"
"code.google.com/p/godec/dec"
)
func main() {
// 1 / 3 is an infinite decimal; it has no exact Dec representation
x, y := dec.NewDecInt64(1), dec.NewDecInt64(3)
z := new(dec.Dec).QuoExact(x, y)
fmt.Println(z)
}
Output: <nil>
Example (Ok) ¶
package main
import (
"fmt"
"code.google.com/p/godec/dec"
)
func main() {
// 1 / 25 is a finite decimal; it has exact Dec representation
x, y := dec.NewDecInt64(1), dec.NewDecInt64(25)
z := new(dec.Dec).QuoExact(x, y)
fmt.Println(z)
}
Output: 0.04
func (*Dec) Round ¶
Round sets z to the value of x rounded to Scale s using Rounder r, and returns z.
func (*Dec) Scan ¶
Scan is a support routine for fmt.Scanner; it sets z to the value of the scanned number. It accepts the decimal formats 'd' and 'f', and handles both equivalently. Bases 2, 8, 16 are not supported. The scale of z is the number of digits after the decimal point (including any trailing 0s), or 0 if there is no decimal point.
Example ¶
package main
import (
"fmt"
"log"
"code.google.com/p/godec/dec"
)
func main() {
// The Scan function is rarely used directly;
// the fmt package recognizes it as an implementation of fmt.Scanner.
d := new(dec.Dec)
_, err := fmt.Sscan("184467440.73709551617", d)
if err != nil {
log.Println("error scanning value:", err)
} else {
fmt.Println(d)
}
}
Output: 184467440.73709551617
func (*Dec) SetScale ¶
SetScale sets the scale of x, with the unscaled value unchanged. The mathematical value of the Dec changes as if it was multiplied by 10**(oldscale-scale).
func (*Dec) SetString ¶
SetString sets z to the value of s, interpreted as a decimal (base 10), and returns z and a boolean indicating success. The scale of z is the number of digits after the decimal point (including any trailing 0s), or 0 if there is no decimal point. If SetString fails, the value of z is undefined but the returned value is nil.
Example ¶
package main
import (
"fmt"
"code.google.com/p/godec/dec"
)
func main() {
d := new(dec.Dec)
d.SetString("012345.67890") // decimal; leading 0 ignored; trailing 0 kept
fmt.Println(d)
}
Output: 12345.67890
func (*Dec) SetUnscaled ¶
SetScale sets the unscaled value of x, with the scale unchanged.
type Rounder ¶
type Rounder interface {
// When UseRemainder() returns true, the Round() method is passed the
// remainder of the division, expressed as the numerator and denominator of
// a rational.
UseRemainder() bool
// Round sets the rounded value of a quotient to z, and returns z.
// quo is rounded down (truncated towards zero) to the scale obtained from
// the Scaler in Quo().
//
// When the remainder is not used, remNum and remDen are nil.
// When used, the remainder is normalized between -1 and 1; that is:
//
// -|remDen| < remNum < |remDen|
//
// remDen has the same sign as y, and remNum is zero or has the same sign
// as x.
Round(z, quo *Dec, remNum, remDen *big.Int) *Dec
}
Rounder represents a method for rounding the (possibly infinite decimal) result of a division to a finite Dec. It is used by Dec.Round() and Dec.Quo().
var RoundCeil Rounder = roundCeil
RoundCeil rounds towards positive infinity; that is, returns the smallest Dec not smaller than the result represented by quo and rem.
The following table shows examples of the results for Quo(x, y, Scale(scale), RoundCeil).
x y scale result ------------------------------ -1.8 10 1 -0.1 -1.5 10 1 -0.1 -1.2 10 1 -0.1 -1.0 10 1 -0.1 -0.8 10 1 -0.0 -0.5 10 1 -0.0 -0.2 10 1 -0.0 0.0 10 1 0.0 0.2 10 1 0.1 0.5 10 1 0.1 0.8 10 1 0.1 1.0 10 1 0.1 1.2 10 1 0.2 1.5 10 1 0.2 1.8 10 1 0.2
var RoundDown Rounder = roundDown
RoundDown rounds towards 0; that is, returns the Dec with the greatest absolute value not exceeding that of the result represented by quo and rem.
The following table shows examples of the results for Quo(x, y, Scale(scale), RoundDown).
x y scale result ------------------------------ -1.8 10 1 -0.1 -1.5 10 1 -0.1 -1.2 10 1 -0.1 -1.0 10 1 -0.1 -0.8 10 1 -0.0 -0.5 10 1 -0.0 -0.2 10 1 -0.0 0.0 10 1 0.0 0.2 10 1 0.0 0.5 10 1 0.0 0.8 10 1 0.0 1.0 10 1 0.1 1.2 10 1 0.1 1.5 10 1 0.1 1.8 10 1 0.1
var RoundExact Rounder = roundExact
RoundExact returns quo if rem is zero, or nil otherwise. It is intended to be used with ScaleQuoExact when it is guaranteed that the result can be obtained without rounding. QuoExact is a shorthand for such a quotient operation.
var RoundFloor Rounder = roundFloor
RoundFloor rounds towards negative infinity; that is, returns the greatest Dec not exceeding the result represented by quo and rem.
The following table shows examples of the results for Quo(x, y, Scale(scale), RoundFloor).
x y scale result ------------------------------ -1.8 10 1 -0.2 -1.5 10 1 -0.2 -1.2 10 1 -0.2 -1.0 10 1 -0.1 -0.8 10 1 -0.1 -0.5 10 1 -0.1 -0.2 10 1 -0.1 0.0 10 1 0.0 0.2 10 1 0.0 0.5 10 1 0.0 0.8 10 1 0.0 1.0 10 1 0.1 1.2 10 1 0.1 1.5 10 1 0.1 1.8 10 1 0.1
var RoundHalfDown Rounder = roundHalfDown
RoundHalfDown rounds to the nearest Dec, and when the remainder is 1/2, it rounds to the Dec with the lower absolute value.
The following table shows examples of the results for Quo(x, y, Scale(scale), RoundHalfDown).
x y scale result ------------------------------ -1.8 10 1 -0.2 -1.5 10 1 -0.1 -1.2 10 1 -0.1 -1.0 10 1 -0.1 -0.8 10 1 -0.1 -0.5 10 1 -0.0 -0.2 10 1 -0.0 0.0 10 1 0.0 0.2 10 1 0.0 0.5 10 1 0.0 0.8 10 1 0.1 1.0 10 1 0.1 1.2 10 1 0.1 1.5 10 1 0.1 1.8 10 1 0.2
var RoundHalfEven Rounder = roundHalfEven
RoundHalfEven rounds to the nearest Dec, and when the remainder is 1/2, it rounds to the Dec with even last digit.
The following table shows examples of the results for Quo(x, y, Scale(scale), RoundHalfEven).
x y scale result ------------------------------ -1.8 10 1 -0.2 -1.5 10 1 -0.2 -1.2 10 1 -0.1 -1.0 10 1 -0.1 -0.8 10 1 -0.1 -0.5 10 1 -0.0 -0.2 10 1 -0.0 0.0 10 1 0.0 0.2 10 1 0.0 0.5 10 1 0.0 0.8 10 1 0.1 1.0 10 1 0.1 1.2 10 1 0.1 1.5 10 1 0.2 1.8 10 1 0.2
var RoundHalfUp Rounder = roundHalfUp
RoundHalfUp rounds to the nearest Dec, and when the remainder is 1/2, it rounds to the Dec with the greater absolute value.
The following table shows examples of the results for Quo(x, y, Scale(scale), RoundHalfUp).
x y scale result ------------------------------ -1.8 10 1 -0.2 -1.5 10 1 -0.2 -1.2 10 1 -0.1 -1.0 10 1 -0.1 -0.8 10 1 -0.1 -0.5 10 1 -0.1 -0.2 10 1 -0.0 0.0 10 1 0.0 0.2 10 1 0.0 0.5 10 1 0.1 0.8 10 1 0.1 1.0 10 1 0.1 1.2 10 1 0.1 1.5 10 1 0.2 1.8 10 1 0.2
var RoundUp Rounder = roundUp
RoundUp rounds away from 0; that is, returns the Dec with the smallest absolute value not smaller than that of the result represented by quo and rem.
The following table shows examples of the results for Quo(x, y, Scale(scale), RoundUp).
x y scale result ------------------------------ -1.8 10 1 -0.2 -1.5 10 1 -0.2 -1.2 10 1 -0.2 -1.0 10 1 -0.1 -0.8 10 1 -0.1 -0.5 10 1 -0.1 -0.2 10 1 -0.1 0.0 10 1 0.0 0.2 10 1 0.1 0.5 10 1 0.1 0.8 10 1 0.1 1.0 10 1 0.1 1.2 10 1 0.2 1.5 10 1 0.2 1.8 10 1 0.2
type Scaler ¶
Scaler represents a method for obtaining the scale to use for the result of an operation on x and y.
var ScaleQuoExact Scaler = scaleQuoExact{}
ScaleQuoExact is the Scaler used by QuoExact. It returns a scale that is greater than or equal to "x.Scale() - y.Scale()"; it is calculated so that the remainder will be zero whenever x/y is a finite decimal.
Source Files