README
¶
numeric
The numeric package for go adds numeric types that aid with number handling.
Documentation
¶
Overview ¶
Package numeric contains structs and interfaces that represent numeric types. It creates wrappers around numeric types, giving them a common interface that can be used to handle numbers (see Numeric interface) and a type that provides user-friendly interaction (see Number type). This package is not intended to replace the builtin types (int, float64, ...), but rather to make number manipulation easier in cases where it's necessary to support a wide range of approximated numbers without the performance penalty of always using an arbitrary precision type (big.Int and big.Rat). It's important to note that since one of the Numeric types is Float, calculations that require exact numbers or decimal precision should not use this package. All types in this package are immutable.
Numeric interface ¶
The default implementations of the Numeric interface (see Float and BigFloat) are aliases to the builtin types (float64 and big.Rat) and, therefore, one may obtain a Numeric value by simply casting to the Numeric type:
x := 15.0 // float64 y := numeric.Float(x) // numeric.Float fmt.Println(y) // => 15
However, Numeric types are merely wrappers around their builtin counterparts and don't provide support for automatic conversion between Numeric types, e.g., when a Float value reaches infinity and needs to be converted to a BigFloat.
Number type ¶
In order to get automatic promotion from a smaller type (e.g. Float) to a larger type (e.g. BigFloat), the Number type should be used.
Usage ¶
A value of Number type can be created through the NewNumber() and NewNumberSafe() methods. Both methods accept an arbitrary type (interface{}), and attempt to convert it to a Number value. If such a conversion does not exist, NewNumberSafe() will return an error and NewNumber() will panic.
x, err := numeric.NewNumberSafe("string")
if err != nil {
handleError(err)
}
Index ¶
- type BigFloat
- func (n *BigFloat) Add(rhs Numeric) Numeric
- func (n *BigFloat) BigRat() (*big.Rat, error)
- func (n *BigFloat) CompareTo(rhs Numeric) int
- func (n *BigFloat) Divide(rhs Numeric) Numeric
- func (n *BigFloat) Float64() (float64, error)
- func (n *BigFloat) Multiply(rhs Numeric) Numeric
- func (n *BigFloat) Negate() Numeric
- func (n *BigFloat) New(value int64) Numeric
- func (n *BigFloat) Promote() Numeric
- func (n *BigFloat) ShouldPromote() bool
- func (n *BigFloat) String() string
- func (n *BigFloat) Subtract(rhs Numeric) Numeric
- type Float
- func (n Float) Add(rhs Numeric) Numeric
- func (n Float) BigRat() (*big.Rat, error)
- func (n Float) CompareTo(rhs Numeric) int
- func (n Float) Divide(rhs Numeric) Numeric
- func (n Float) Float64() (float64, error)
- func (n Float) Multiply(rhs Numeric) Numeric
- func (n Float) Negate() Numeric
- func (n Float) New(value int64) Numeric
- func (n Float) Promote() Numeric
- func (n Float) ShouldPromote() bool
- func (n Float) String() string
- func (n Float) Subtract(rhs Numeric) Numeric
- type Number
- func (n Number) Add(rhs Number) Number
- func (n Number) BigInt() *big.Int
- func (n Number) BigRat() *big.Rat
- func (n Number) CompareTo(rhs Number) int
- func (n Number) Divide(rhs Number) Number
- func (n Number) Equals(rhs Number) bool
- func (n Number) Float64() float64
- func (n Number) Int64() (int64, error)
- func (n Number) Multiply(rhs Number) Number
- func (n Number) Negative() Number
- func (n Number) String() string
- func (n Number) Subtract(rhs Number) Number
- type Numeric
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BigFloat ¶
BigFloat is an implementation of the Numeric interface for the big.Rat type. It cannot be promoted.
func (*BigFloat) CompareTo ¶
CompareTo compares n to rhs and returns 1 if n is greater than rhs, -1 if it's smaller than rhs and 0 if the two values are equivalent.
func (*BigFloat) Float64 ¶
Float64 converts this BigFloat to a float64 value and returns it. If the value is too large or too small, an error will be returned and the result of the conversion will be +/- infinity, respectively.
func (*BigFloat) ShouldPromote ¶
ShouldPromote returns false for *BigFloat.
type Float ¶
type Float float64
Float is an implementation of the Numeric interface for the float64 type. It can be promoted to a BigFloat and will return true on ShouldPromote() if it's equal to +/-Infinity or NaN.
func (Float) BigRat ¶
BigRat converts this float to a big.Rat value and returns it. If the value is +/-Infinity or NaN, an error will be returned. For +Infinity, the result will be set to math.MaxFloat64 + math.SmallestNonzeroFloat64 and for -Infinity, the negative of that will be returned. If n is NaN, the result will be 0.
func (Float) CompareTo ¶
CompareTo compares n to rhs and returns 1 if n is greater than rhs, -1 if it's smaller than rhs and 0 if the two values are equivalent.
func (Float) ShouldPromote ¶
ShouldPromote returns true only if n is +/-Infinity or NaN.
type Number ¶
type Number struct {
// contains filtered or unexported fields
}
Number stores a numeric value using a Numeric type as its underlying storage. It can be created through the NewNumber and NewNumberSafe methods.
func NewNumber ¶
func NewNumber(value interface{}) Number
NewNumber attempts to convert a value to a Number and panics if it fails.
func NewNumberSafe ¶
NewNumberSafe attempts to convert a value to a Number and returns an error if it fails.
func (Number) Add ¶
Add returns a Number that is the sum of n and rhs and automatically promotes it if required.
func (Number) CompareTo ¶
CompareTo compares n to rhs and returns 1 if n is greater than rhs, -1 if it's smaller than rhs and 0 if the two values are equivalent.
func (Number) Divide ¶
Divide returns a Number that is the quotient of n and rhs and automatically promotes it if required.
func (Number) Equals ¶
Equals compares n to rhs and returns 1 if n is greater than rhs, -1 if it's smaller than rhs and 0 if the two values are equivalent.
func (Number) Float64 ¶
Float64 returns a float64 with the value of n. If the value is invalid, too large or too small, the values NaN and +/-Infinity may be returned.
func (Number) Int64 ¶
Int64 returns an int64 with the value of n. If n cannot be represented as an int64, an error will be returned and the result of Int64() will be a sensible attempt to represent n.
func (Number) Multiply ¶
Multiply returns a Number that is the product of n and rhs and automatically promotes it if required.
type Numeric ¶
type Numeric interface {
New(value int64) Numeric
Negate() Numeric
Add(rhs Numeric) Numeric
Subtract(rhs Numeric) Numeric
Multiply(rhs Numeric) Numeric
Divide(rhs Numeric) Numeric
Float64() (float64, error)
BigRat() (*big.Rat, error)
CompareTo(rhs Numeric) int
ShouldPromote() bool
Promote() Numeric
String() string
}
Numeric is an interface that represents any numeric type, such as float64. Default implementations exist for the types float64 (type Float) and big.Rat(type BigFloat).
Method New() should return the value provided. The Negate(), Add(), Subtract(), Multiply() and Divide() methods are aliases for the corresponding operations. To compare two Numeric values, the method CompareTo() should be called. For inputs x and y, it should return:
x.CompareTo(y) // 0 if x == y // 1 if x > y // -1 if x < y
The available conversion methods are Float64() and BigRat(). Both of these methods return the result and an error, which should represent overflow or invalid conversion errors. If an error occurs, the methods should attempt to return a sensible value, but may fallback to the default zero value. Numeric also supports string conversion through the Stringer interface.
Promote() and ShouldPromote() are part of a value promotion system. If a value is to big or small to be adequately represented in its Numeric type, it can be promoted (converted) to a type that has a larger capacity. If this happens, the method ShouldPromote() should return true and the method Promote() should return the promoted value.
Source Files