README
¶
Number
Package number is a from scratch implementation of arbitrary-precision decimal floating point numbers and associated arithmetic.
Currently the only supported type is Real, which represents a real (ℝ)
number. Eventually complex (ℂ) and rational (ℚ) numbers will be supported.
Arithmetic operations do not modify their operands and return values are always deep copies of underlying data. This simplifies programming patterns, but causes additional memory usage. Additionally, return values of operations will have the precision of the operand with the largest precision and the rounding mode of the receiver operand.
Example
package main
import (
"fmt"
"github.com/djfritz/number"
)
func main() {
x := number.NewInt64(5)
y, _ := number.ParseReal("-1.234e-2", number.DefaultPrecision)
z := x.Add(y) // x and y are unmodified
zln := z.Ln().Sub(number.NewInt64(2)) // it's possible to chain operations
fmt.Printf("x = %v\n", x) // the %v verb prints the number in the most natural way, depending on the number
fmt.Printf("y = %.9f\n", y) // precision with the %f verb works as expected
fmt.Printf("z = %e\n", z) // as does scientific notation
fmt.Printf("ln(z)-2 = %v\n", zln)
}
Results in:
x = 5
y = -0.01234
z = 4.98766e0
ln(z)-2 = -0.393033138098075529994326559359829
Real numbers
A zero value for a Real represents the number 0, and new values can be used in this way:
x := new(Real) // 0
Real currently supports three rounding modes:
- Round to nearest even (the default and the default for IEEE-754 floating point numbers)
- Round to nearest
- Round to zero (truncate)
The default precision is 34, which is equivalent to IEEE-754-2008 128-bit decimal floating point numbers.
Tests
Beyond the unit tests in this package, Real is tested against Mike Cowlishaw's excellent dectest tests. Those tests are kept in another package, mostly to avoid embedding an ICU license in this package.
Currently, 8761 of the subset dectest tests are run against Real. Six of those currently fail, but only because of inexact rounding expected in the test suite. Real computes to better than .5ulp in those cases and provides a more accurate answer.
Documentation
¶
Overview ¶
Package number implements arbitrary-precision decimal floating point numbers and associated arithmetic.
Currently the only supported type is `Real`, which represents a real (ℝ) number. Eventually complex (ℂ) and rational (ℚ) numbers will be supported.
Arithmetic operations do not modify their operands and return values are always deep copies of underlying data. This simplifies programming patterns, but causes additional memory usage. Additionally, return values of operations will have the precision of the operand with the largest precision and the rounding mode of the receiver operand.
A zero value for a Real represents the number 0, and new values can be used in this way:
``` x := new(Real) // 0 ```
Real currently supports three rounding modes:
- Round to nearest even (the default and the default for IEEE-754 floating point numbers) - Round to nearest - Round to zero (truncate)
The default precision is 34, which is equivalent to IEEE-754-2008 128-bit decimal floating point numbers.
Index ¶
- Constants
- Variables
- type Real
- func (x *Real) Abs() *Real
- func (x *Real) Add(y *Real) *Real
- func (x *Real) Ceiling() *Real
- func (x *Real) Compare(y *Real) int
- func (x *Real) Copy() *Real
- func (x *Real) CopyValue(y *Real)
- func (x *Real) Cos() *Real
- func (x *Real) Div(y *Real) *Real
- func (x *Real) Exp() *Real
- func (x *Real) Factorial() *Real
- func (x *Real) Float64() (float64, error)
- func (x *Real) Floor() *Real
- func (x *Real) Format(s fmt.State, verb rune)
- func (x *Real) GobDecode(b []byte) error
- func (x *Real) GobEncode() ([]byte, error)
- func (x *Real) Int64() (int64, error)
- func (x *Real) Integer() *Real
- func (x *Real) IsInf() bool
- func (x *Real) IsInteger() bool
- func (x *Real) IsNaN() bool
- func (x *Real) IsZero() bool
- func (x *Real) Ln() *Real
- func (x *Real) Max(y *Real) *Real
- func (x *Real) Min(y *Real) *Real
- func (x *Real) Mod(y *Real) *Real
- func (x *Real) Mode() int
- func (x *Real) Mul(y *Real) *Real
- func (x *Real) Pow(y *Real) *Real
- func (x *Real) Precision() uint
- func (x *Real) Reciprocal() *Real
- func (x *Real) Remainder(y *Real) *Real
- func (x *Real) RoundedInteger() *Real
- func (x *Real) SetFloat64(y float64)
- func (x *Real) SetInt64(y int64)
- func (x *Real) SetMode(m int) error
- func (x *Real) SetPrecision(y uint)
- func (x *Real) SetUint64(y uint64)
- func (x *Real) Sin() *Real
- func (x *Real) Sqrt() *Real
- func (x *Real) String() string
- func (x *Real) Sub(y *Real) *Real
- func (x *Real) Tan() *Real
- func (x *Real) Uint64() (uint64, error)
Constants ¶
const ( FormReal = iota // A finite real number FormNaN // Not a number FormInf // Infinity )
Number forms
const ( ModeNearestEven = iota ModeNearest ModeZero )
Rounding modes.
const DefaultPrecision = 34
The default precision for a real number. Expressed in decimal digits. 34 digits is equivalent IEEE-754-2008 128-bit decimal floating point.
const MaxExpIterations = 1000
MaxExpIterations is the maximum number of iterations in the Taylor series approximation of eˣ. If this limit is reached, Exp() will panic.
const MaxTrigIterations = 1000
MaxTrigIterations is the maximum number of iterations in the Taylor series approximation of trigonometric functions. If this limit is reached, the function will panic.
Variables ¶
var (
ErrInvalidCharacter = errors.New("invalid character")
)
var ErrInvalidMode = errors.New("invalid mode")
Functions ¶
This section is empty.
Types ¶
type Real ¶
type Real struct {
// contains filtered or unexported fields
}
A real number. Internally stored as a real number in decimal scientific notation.
func NewFloat64 ¶
Return a new real number set to the given float64, with the default rounding mode and precision.
func NewInt64 ¶
Return a new real number set to the given signed int64, with the default rounding mode and precision.
func NewUint64 ¶
Return a new real number set to the given unsigned uint64, with the default rounding mode and precision.
func ParseReal ¶
ParseReal converts a string s to a Real with the given precision p.
Input beyond the given precision is ignored but not considered an error.
Input can be as a fixed precision number or in scientific notation, using a lower case 'e' for the exponent.
func (*Real) Compare ¶
Compare x with y, returing an integer representing:
1 : x > y 0 : x == y -1 : x < y
func (*Real) CopyValue ¶
Copy just the value of y into x, leaving x's precision and mode the same. The result will round if needed.
func (*Real) Factorial ¶
Factorial returns the integer factorial of x. If x is not an integer, the integer portion of x is used.
func (*Real) Float64 ¶
Return a float64 representation of the number, if possible. If not possible, err will be non-nil.
func (*Real) Format ¶
Format implements fmt.Formatter. It acccepts 'd', 'e', 'f', and 'v' verbs. The 'd' verb will return an integer with trailing zeros. 'e' is the same as String(), and returns the value in scientific notation. 'f' returns a floating point value, and accepts precision modifiers. 'v' will choose an appropriate form based on the magnitude of the number.
func (*Real) GobDecode ¶
GobDecode implements the encoding/gob.GobDecoder interface.
func (*Real) GobEncode ¶
GobEncode implements the encoding/gob.GobEncoder interface.
func (*Real) Int64 ¶
Return an int64 representation of the number, if possible. If not possible, err will be non-nil.
func (*Real) Mod ¶
Return the modulus x%y. If either x or y are not integers, they will be truncated before the operation.
func (*Real) RoundedInteger ¶
Return the rounded integer part of a real number.
func (*Real) SetFloat64 ¶
Set a real number to the given float64. Rounding mode and precision are left unchanged. If precision is lower than the given value, rounding occurs.
func (*Real) SetInt64 ¶
Set a real number to the given signed int64. Rounding mode and precision are left unchanged. If precision is lower than the given value, rounding occurs.
func (*Real) SetPrecision ¶
Set the precision of the given number and round if necessary.
func (*Real) SetUint64 ¶
Set a real number to the given unsigned uint64. Rounding mode and precision are left unchanged. If precision is lower than the given value, rounding occurs.
Source Files