decimal

README

Decimal arithmetic

Arithmetic that works on a type alias of json.Number, inspired by SQLite.

Since Number is a string, literals are valid numbers, and you can do:

decimal.Sum("0.1", "0.1", "0.1", "-0.3") // == "0"

All operations produce exact results, with arbitrary precision (which is why we can't have decimal.Div).

Instead, we have decimal.Split (and decimal.Allocate) to distribute an amount amongst parties without loosing units to rounding.

decimal.Split("0.99", "0.01", 2) // == ["0.5", "0.49"]
decimal.Allocate("100", "0.05", 2, 3, 2) // == ["28.6", "48.85", "28.55"]

We also have operations to round amounts to multiples of a unit under various rounding modes.

The library won't win any performance prizes, but you may find the API more ergonomic than alternatives.

Documentation

Overview

Package decimal implements arbitrary-precision decimal arithmetic.

Index

• func Cmp(x, y Number) int
• func IsInt(x Number) bool
• func IsValid(x Number) bool
• type Fmt
  • func (x Fmt) Format(f fmt.State, v rune)
• type Number
  • func Abs(x Number) Number
  • func Add(x, y Number) Number
  • func Allocate(amount, unit Number, ratios ...uint) []Number
  • func Ceil(x, unit Number) Number
  • func Float64(f float64) Number
  • func Floor(x, unit Number) Number
  • func Int64(i int64) Number
  • func Mul(x, y Number) Number
  • func Neg(x Number) Number
  • func Pow(x Number, n uint) Number
  • func Prod(n ...Number) Number
  • func Round(x, unit Number) Number
  • func RoundToEven(x, unit Number) Number
  • func Split(amount, unit Number, n uint) []Number
  • func Sub(x, y Number) Number
  • func Sum(n ...Number) Number
  • func Trunc(x, unit Number) Number

Functions

func Cmp

func Cmp(x, y Number) int

Cmp compares x and y, like cmp.Compare.

func IsInt

func IsInt(x Number) bool

IsInt reports whether x is an integer.

func IsValid

func IsValid(x Number) bool

IsValid reports whether x is a valid JSON number literal.

Types

type Fmt

type Fmt Number

Fmt is a formatter for a decimal number.

func (Fmt) Format

func (x Fmt) Format(f fmt.State, v rune)

Format implements fmt.Formatter. It accepts the formats for decimal floating-point numbers: 'e', 'E', 'f', 'F', 'g', 'G'. The 'v' format is handled like 'g'.

type Number

type Number = json.Number

A Number is an arbitrary precision decimal number, stored as JSON text.

func Abs

func Abs(x Number) Number

Abs returns |x| (the absolute value of x).

func Add

func Add(x, y Number) Number

Add returns the sum x + y.

func Allocate

func Allocate(amount, unit Number, ratios ...uint) []Number

Allocate allocates an integer amount of units according to a list of ratios. Leftover units are distributed round-robin, from left to right.

func Ceil

func Ceil(x, unit Number) Number

Ceil returns the least multiple of unit greater than or equal to x.

func Float64

func Float64(f float64) Number

Float64 converts f into a decimal number.

func Floor

func Floor(x, unit Number) Number

Floor returns the greatest multiple of unit less than or equal to x.

func Int64

func Int64(i int64) Number

Int64 converts i into a decimal number.

func Mul

func Mul(x, y Number) Number

Mul returns the product x * y.

func Neg

func Neg(x Number) Number

Neg returns -x (x with its sign negated).

func Pow

func Pow(x Number, n uint) Number

Pow returns xⁿ (the nth power of x).

func Prod

func Prod(n ...Number) Number

Prod returns the product of all n.

func Round

func Round(x, unit Number) Number

Round rounds x to the nearest multiple of unit, with ties away from zero.

func RoundToEven

func RoundToEven(x, unit Number) Number

RoundToEven rounds x to the nearest multiple of unit, with ties to an even multiple of unit.

func Split

func Split(amount, unit Number, n uint) []Number

Split splits an integer amount of units over n parties. Leftover units are distributed round-robin, from left to right.

func Sub

func Sub(x, y Number) Number

Sub returns the difference x - y.

func Sum

func Sum(n ...Number) Number

Sum returns the sum of all n.

func Trunc

func Trunc(x, unit Number) Number

Trunc rounds x toward zero, to a multiple of unit.