apd

package
Version: v0.0.0-...-927e444 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 23, 2020 License: Apache-2.0, Apache-2.0 Imports: 6 Imported by: 0

README

apd

apd is an arbitrary-precision decimal package for Go.

Documentation

https://godoc.org/github.com/cockroachdb/apd

Goals

  • panic-free operation; use errors when necessary
  • defined performance (speed of operations can be defined by, i.e., size of input and precision)
  • accurate precision (an operation performed with requested precision will use enough precision during internal operations to achieve desired result)

Testing

Testing is done primarily with the suite from General Decimal Arithmetic, which contains thousands of tests for various operations.

Documentation

Overview

Package apd implements arbitrary-precision decimals.

Index

Constants

View Source
const (

	// MaxExponent is the highest exponent supported. Exponents near this range will
	// perform very slowly (many seconds per operation).
	MaxExponent = 100000
	// MinExponent is the lowest exponent supported with the same limitations as
	// MaxExponent.
	MinExponent = -MaxExponent
)
View Source
const (
	// DefaultTraps is the default trap set used by BaseContext.
	DefaultTraps = SystemOverflow |
		SystemUnderflow |
		Overflow |
		Underflow |
		Subnormal |
		DivisionUndefined |
		DivisionByZero |
		DivisionImpossible |
		InvalidOperation
)

Variables

View Source
var BaseContext = Context{

	Precision: 0,

	MaxExponent: MaxExponent,
	MinExponent: MinExponent,

	Traps: DefaultTraps,
}

BaseContext is a useful default Context. Should not be mutated.

Functions

func NewFromString

func NewFromString(s string) (*Decimal, Condition, error)

NewFromString creates a new decimal from s. It has no restrictions on exponents or precision.

func NumDigits

func NumDigits(b *big.Int) int64

NumDigits returns the number of decimal digits of b.

Types

type Condition

type Condition uint32

Condition holds condition flags.

const (
	// SystemOverflow is raised when an exponent is greater than MaxExponent.
	SystemOverflow Condition = 1 << iota
	// SystemUnderflow is raised when an exponent is less than MinExponent.
	SystemUnderflow
	// Overflow is raised when an exponent is greater than Context.MaxExponent.
	Overflow
	// Underflow is raised when an exponent is less than Context.MinExponent.
	Underflow
	// Inexact is raised when an operation is not exact.
	Inexact
	// Subnormal is raised when an operation's adjusted exponent is less than
	// Context.MinExponent.
	Subnormal
	// Rounded is raised when rounding occurs.
	Rounded
	// DivisionUndefined is raised when both division operands are 0.
	DivisionUndefined
	// DivisionByZero is raised when the divisor is zero.
	DivisionByZero
	// DivisionImpossible is raised when integer division cannot be exactly
	// represented with the given precision.
	DivisionImpossible
	// InvalidOperation is raised during an invalid operation.
	InvalidOperation
	// Clamped is raised when the exponent of a result has been altered or
	// constrained in order to fit the constraints of a specific concrete
	// representation.
	Clamped
)

func (Condition) Any

func (r Condition) Any() bool

Any returns true if any flag is true.

func (Condition) Clamped

func (r Condition) Clamped() bool

Clamped returns true if the Clamped flag is set.

func (Condition) DivisionByZero

func (r Condition) DivisionByZero() bool

DivisionByZero returns true if the DivisionByZero flag is set.

func (Condition) DivisionImpossible

func (r Condition) DivisionImpossible() bool

DivisionImpossible returns true if the DivisionImpossible flag is set.

func (Condition) DivisionUndefined

func (r Condition) DivisionUndefined() bool

DivisionUndefined returns true if the DivisionUndefined flag is set.

func (Condition) GoError

func (r Condition) GoError(traps Condition) (Condition, error)

GoError converts r to an error based on the given traps and returns r. Traps are the conditions which will trigger an error result if the corresponding Flag condition occurred.

func (Condition) Inexact

func (r Condition) Inexact() bool

Inexact returns true if the Inexact flag is set.

func (Condition) InvalidOperation

func (r Condition) InvalidOperation() bool

InvalidOperation returns true if the InvalidOperation flag is set.

func (Condition) Overflow

func (r Condition) Overflow() bool

Overflow returns true if the Overflow flag is set.

func (Condition) Rounded

func (r Condition) Rounded() bool

Rounded returns true if the Rounded flag is set.

func (Condition) String

func (r Condition) String() string

func (Condition) Subnormal

func (r Condition) Subnormal() bool

Subnormal returns true if the Subnormal flag is set.

func (Condition) SystemOverflow

func (r Condition) SystemOverflow() bool

SystemOverflow returns true if the SystemOverflow flag is set.

func (Condition) SystemUnderflow

func (r Condition) SystemUnderflow() bool

SystemUnderflow returns true if the SystemUnderflow flag is set.

func (Condition) Underflow

func (r Condition) Underflow() bool

Underflow returns true if the Underflow flag is set.

type Context

type Context struct {
	// Precision is the number of places to round during rounding; this is
	// effectively the total number of digits (before and after the decimal
	// point).
	Precision uint32
	// Rounding specifies the Rounder to use during rounding. RoundHalfUp is used if
	// nil.
	Rounding Rounder
	// MaxExponent specifies the largest effective exponent. The
	// effective exponent is the value of the Decimal in scientific notation. That
	// is, for 10e2, the effective exponent is 3 (1.0e3). Zero (0) is not a special
	// value; it does not disable this check.
	MaxExponent int32
	// MinExponent is similar to MaxExponent, but for the smallest effective
	// exponent.
	MinExponent int32
	// Traps are the conditions which will trigger an error result if the
	// corresponding Flag condition occurred.
	Traps Condition
}

Context maintains options for Decimal operations. It can safely be used concurrently, but not modified concurrently.

func (*Context) Abs

func (c *Context) Abs(d, x *Decimal) (Condition, error)

Abs sets d to |x| (the absolute value of x).

func (*Context) Add

func (c *Context) Add(d, x, y *Decimal) (Condition, error)

Add sets d to the sum x+y.

func (*Context) Cbrt

func (c *Context) Cbrt(d, x *Decimal) (Condition, error)

Cbrt sets d to the cube root of x.

func (*Context) Ceil

func (c *Context) Ceil(d, x *Decimal) (Condition, error)

Ceil sets d to the smallest integer >= x.

func (*Context) Exp

func (c *Context) Exp(d, x *Decimal) (Condition, error)

Exp sets d = e**x.

func (*Context) Floor

func (c *Context) Floor(d, x *Decimal) (Condition, error)

Floor sets d to the largest integer <= x.

func (*Context) Ln

func (c *Context) Ln(d, x *Decimal) (Condition, error)

Ln sets d to the natural log of x.

func (*Context) Log10

func (c *Context) Log10(d, x *Decimal) (Condition, error)

Log10 sets d to the base 10 log of x.

func (*Context) Mul

func (c *Context) Mul(d, x, y *Decimal) (Condition, error)

Mul sets d to the product x*y.

func (*Context) Neg

func (c *Context) Neg(d, x *Decimal) (Condition, error)

Neg sets d to -x.

func (*Context) NewFromString

func (c *Context) NewFromString(s string) (*Decimal, Condition, error)

NewFromString creates a new decimal from s. The returned Decimal has its exponents restricted by the context and its value rounded if it contains more digits than the context's precision.

func (*Context) Pow

func (c *Context) Pow(d, x, y *Decimal) (Condition, error)

Pow sets d = x**y.

func (*Context) Quantize

func (c *Context) Quantize(d, v *Decimal, exp int32) (Condition, error)

Quantize adjusts and rounds v as necessary so it is represented with exponent exp and stores the result in d.

func (*Context) Quo

func (c *Context) Quo(d, x, y *Decimal) (Condition, error)

Quo sets d to the quotient x/y for y != 0. c.Precision must be > 0. If an exact division is required, use a context with high precision and verify it was exact by checking the Inexact flag on the return Condition.

func (*Context) QuoInteger

func (c *Context) QuoInteger(d, x, y *Decimal) (Condition, error)

QuoInteger sets d to the integer part of the quotient x/y. If the result cannot fit in d.Precision digits, an error is returned.

func (*Context) Reduce

func (c *Context) Reduce(d, x *Decimal) (Condition, error)

Reduce sets d to x with all trailing zeros removed.

func (*Context) Rem

func (c *Context) Rem(d, x, y *Decimal) (Condition, error)

Rem sets d to the remainder part of the quotient x/y. If the integer part cannot fit in d.Precision digits, an error is returned.

func (*Context) Round

func (c *Context) Round(d, x *Decimal) (Condition, error)

Round sets d to rounded x, rounded to the precision specified by c. If c has zero precision, no rounding will occur. If c has no Rounding specified, RoundHalfUp is used.

func (*Context) SetString

func (c *Context) SetString(d *Decimal, s string) (*Decimal, Condition, error)

SetString sets d to s and returns d. The returned Decimal has its exponents restricted by the context and its value rounded if it contains more digits than the context's precision.

func (*Context) Sqrt

func (c *Context) Sqrt(d, x *Decimal) (Condition, error)

Sqrt sets d to the square root of x.

func (*Context) Sub

func (c *Context) Sub(d, x, y *Decimal) (Condition, error)

Sub sets d to the difference x-y.

func (*Context) ToIntegral

func (c *Context) ToIntegral(d, x *Decimal) (Condition, error)

ToIntegral sets d to integral value of x. Inexact and Rounded flags are ignored and removed.

func (*Context) ToIntegralX

func (c *Context) ToIntegralX(d, x *Decimal) (Condition, error)

ToIntegralX sets d to integral value of x.

func (*Context) WithPrecision

func (c *Context) WithPrecision(p uint32) *Context

WithPrecision returns a copy of c but with the specified precision.

type Decimal

type Decimal struct {
	Coeff    big.Int
	Exponent int32
}

Decimal is an arbitrary-precision decimal. Its value is:

Coeff * 10 ^ Exponent

func New

func New(coeff int64, exponent int32) *Decimal

New creates a new decimal with the given coefficient and exponent.

func NewWithBigInt

func NewWithBigInt(coeff *big.Int, exponent int32) *Decimal

NewWithBigInt creates a new decimal with the given coefficient and exponent.

func (*Decimal) Abs

func (d *Decimal) Abs(x *Decimal) *Decimal

Abs sets d to |x| and returns d.

func (*Decimal) Cmp

func (d *Decimal) Cmp(x *Decimal) int

Cmp compares d and x and returns:

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

func (*Decimal) Float64

func (d *Decimal) Float64() (float64, error)

Float64 returns the float64 representation of x. This conversion may lose data (see strconv.ParseFloat for caveats).

func (*Decimal) Int64

func (d *Decimal) Int64() (int64, error)

Int64 returns the int64 representation of x. If x cannot be represented in an int64, an error is returned.

func (*Decimal) Modf

func (d *Decimal) Modf(integ, frac *Decimal)

Modf sets integ to the integral part of d and frac to the fractional part such that d = integ+frac. If d is negative, both integ or frac will be either 0 or negative. integ.Exponent will be >= 0; frac.Exponent will be <= 0.

func (*Decimal) Neg

func (d *Decimal) Neg(x *Decimal) *Decimal

Neg sets d to -x and returns d.

func (*Decimal) NumDigits

func (d *Decimal) NumDigits() int64

NumDigits returns the number of decimal digits of d.Coeff.

func (*Decimal) Reduce

func (d *Decimal) Reduce(x *Decimal) *Decimal

Reduce sets d to x with all trailing zeros removed and returns d.

func (*Decimal) Set

func (d *Decimal) Set(x *Decimal) *Decimal

Set sets d's Coefficient and Exponent from x and returns d.

func (*Decimal) SetCoefficient

func (d *Decimal) SetCoefficient(x int64) *Decimal

SetCoefficient sets d's Coefficient value to x and returns d. The Exponent is not changed.

func (*Decimal) SetExponent

func (d *Decimal) SetExponent(x int32) *Decimal

SetExponent sets d's Exponent value to x and returns d.

func (*Decimal) SetFloat64

func (d *Decimal) SetFloat64(f float64) (*Decimal, error)

SetFloat64 sets d's Coefficient and Exponent to x and returns d. d will hold the exact value of f.

func (*Decimal) SetString

func (d *Decimal) SetString(s string) (*Decimal, Condition, error)

SetString sets d to s and returns d. It has no restrictions on exponents or precision.

func (*Decimal) Sign

func (d *Decimal) Sign() int

Sign returns:

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

func (*Decimal) String

func (d *Decimal) String() string

String is a wrapper of ToSci.

func (*Decimal) ToSci

func (d *Decimal) ToSci() string

ToSci returns d in scientific notation if an exponent is needed.

func (*Decimal) ToStandard

func (d *Decimal) ToStandard() string

ToStandard converts d to a standard notation string (i.e., no exponent part). This can result in long strings given large exponents.

type ErrDecimal

type ErrDecimal struct {
	Ctx *Context
	// Flags are the accumulated flags from operations.
	Flags Condition
	// contains filtered or unexported fields
}

ErrDecimal performs operations on decimals and collects errors during operations. If an error is already set, the operation is skipped. Designed to be used for many operations in a row, with a single error check at the end.

func MakeErrDecimal

func MakeErrDecimal(c *Context) ErrDecimal

MakeErrDecimal creates a ErrDecimal with given context.

func (*ErrDecimal) Abs

func (e *ErrDecimal) Abs(d, x *Decimal) *Decimal

Abs performs e.Ctx.Abs(d, x) and returns d.

func (*ErrDecimal) Add

func (e *ErrDecimal) Add(d, x, y *Decimal) *Decimal

Add performs e.Ctx.Add(d, x, y) and returns d.

func (*ErrDecimal) Ceil

func (e *ErrDecimal) Ceil(d, x *Decimal) *Decimal

Ceil performs e.Ctx.Ceil(d, x) and returns d.

func (*ErrDecimal) Err

func (e *ErrDecimal) Err() error

Err returns the first error encountered or the context's trap error if present.

func (*ErrDecimal) Exp

func (e *ErrDecimal) Exp(d, x *Decimal) *Decimal

Exp performs e.Ctx.Exp(d, x) and returns d.

func (*ErrDecimal) Floor

func (e *ErrDecimal) Floor(d, x *Decimal) *Decimal

Floor performs e.Ctx.Floor(d, x) and returns d.

func (*ErrDecimal) Int64

func (e *ErrDecimal) Int64(d *Decimal) int64

Int64 returns 0 if err is set. Otherwise returns d.Int64().

func (*ErrDecimal) Ln

func (e *ErrDecimal) Ln(d, x *Decimal) *Decimal

Ln performs e.Ctx.Ln(d, x) and returns d.

func (*ErrDecimal) Log10

func (e *ErrDecimal) Log10(d, x *Decimal) *Decimal

Log10 performs d.Log10(x) and returns d.

func (*ErrDecimal) Mul

func (e *ErrDecimal) Mul(d, x, y *Decimal) *Decimal

Mul performs e.Ctx.Mul(d, x, y) and returns d.

func (*ErrDecimal) Neg

func (e *ErrDecimal) Neg(d, x *Decimal) *Decimal

Neg performs e.Ctx.Neg(d, x) and returns d.

func (*ErrDecimal) Pow

func (e *ErrDecimal) Pow(d, x, y *Decimal) *Decimal

Pow performs e.Ctx.Pow(d, x, y) and returns d.

func (*ErrDecimal) Quantize

func (e *ErrDecimal) Quantize(d, v *Decimal, exp int32) *Decimal

Quantize performs e.Ctx.Quantize(d, v, exp) and returns d.

func (*ErrDecimal) Quo

func (e *ErrDecimal) Quo(d, x, y *Decimal) *Decimal

Quo performs e.Ctx.Quo(d, x, y) and returns d.

func (*ErrDecimal) QuoInteger

func (e *ErrDecimal) QuoInteger(d, x, y *Decimal) *Decimal

QuoInteger performs e.Ctx.QuoInteger(d, x, y) and returns d.

func (*ErrDecimal) Reduce

func (e *ErrDecimal) Reduce(d, x *Decimal) *Decimal

Reduce performs e.Ctx.Reduce(d, x) and returns d.

func (*ErrDecimal) Rem

func (e *ErrDecimal) Rem(d, x, y *Decimal) *Decimal

Rem performs e.Ctx.Rem(d, x, y) and returns d.

func (*ErrDecimal) Round

func (e *ErrDecimal) Round(d, x *Decimal) *Decimal

Round performs e.Ctx.Round(d, x) and returns d.

func (*ErrDecimal) Sqrt

func (e *ErrDecimal) Sqrt(d, x *Decimal) *Decimal

Sqrt performs e.Ctx.Sqrt(d, x) and returns d.

func (*ErrDecimal) Sub

func (e *ErrDecimal) Sub(d, x, y *Decimal) *Decimal

Sub performs e.Ctx.Sub(d, x, y) and returns d.

func (*ErrDecimal) ToIntegral

func (e *ErrDecimal) ToIntegral(d, x *Decimal) *Decimal

ToIntegral performs e.Ctx.ToIntegral(d, x) and returns d.

func (*ErrDecimal) ToIntegralX

func (e *ErrDecimal) ToIntegralX(d, x *Decimal) *Decimal

ToIntegralX performs e.Ctx.ToIntegralX(d, x) and returns d.

type Rounder

type Rounder func(result *big.Int, half int) bool

Rounder defines a function that returns true if 1 should be added to the absolute value of a number being rounded. result is the result to which the 1 would be added. half is -1 if the discarded digits are < 0.5, 0 if = 0.5, or 1 if > 0.5.

var (
	// RoundDown rounds toward 0; truncate.
	RoundDown Rounder = roundDown
	// RoundHalfUp rounds up if the digits are >= 0.5.
	RoundHalfUp Rounder = roundHalfUp
	// RoundHalfEven rounds up if the digits are > 0.5. If the digits are equal
	// to 0.5, it rounds up if the previous digit is odd, always producing an
	// even digit.
	RoundHalfEven Rounder = roundHalfEven
	// RoundCeiling towards +Inf: rounds up if digits are > 0 and the number
	// is positive.
	RoundCeiling Rounder = roundCeiling
	// RoundFloor towards -Inf: rounds up if digits are > 0 and the number
	// is negative.
	RoundFloor Rounder = roundFloor
	// RoundHalfDown rounds up if the digits are > 0.5.
	RoundHalfDown Rounder = roundHalfDown
	// RoundUp rounds away from 0.
	RoundUp Rounder = roundUp
	// Round05Up rounds zero or five away from 0; same as round-up, except that
	// rounding up only occurs if the digit to be rounded up is 0 or 5.
	Round05Up Rounder = round05Up
)

func (Rounder) Round

func (r Rounder) Round(c *Context, d, x *Decimal) Condition

Round sets d to rounded x.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL