rounding

README

go-rounding

Rounding and truncation methods for big.Rat to close some of the gap in functionality between Rat and Decimal (such as Java's BigDecimal).

Documentation on GoDoc: http://godoc.org/github.com/wadey/go-rounding.

Why go-rounding?

There are a few other Decimal implementations for Go:

• dec
• inf

So why does go-rounding exist? big.Rat is a superset of the basic needs for a Decimal representation, the only major thing missing is some nice rounding methods. go-rounding is less than 150 lines of code, so it is easy to review and understand its implementation. If you need more features, you should use one of the above packages.

Benchmark

To run:

go test -v -benchmem -bench .

Example output on go1.5 darwin_amd64 commit 55c986f658

BenchmarkFinite          2000000           651 ns/op         182 B/op          3 allocs/op
BenchmarkFinitePrec      2000000           996 ns/op         244 B/op          5 allocs/op
BenchmarkRoundUp         1000000          2470 ns/op         397 B/op          9 allocs/op
BenchmarkRoundHalfEven   1000000          2458 ns/op         393 B/op          9 allocs/op
BenchmarkTrunc            500000          2669 ns/op         265 B/op          6 allocs/op

Documentation

Overview

Package rounding provides rounding and truncation methods for big.Rat. It uses the same rounding terminology as Java's BigDecimal.

For more information see the README at:

https://github.com/wadey/go-rounding

Index

• func Finite(x *big.Rat) bool
• func FinitePrec(x *big.Rat) int
• func FiniteString(x *big.Rat) string
• func FiniteStringMin(x *big.Rat, prec int) string
• func Round(x *big.Rat, prec int, method RoundingMode) *big.Rat
• func Trunc(x *big.Rat, prec int) *big.Rat
• type RoundingMode

Examples

• Finite
• FinitePrec
• FiniteString
• FiniteStringMin
• Round
• Trunc

Functions

func Finite

func Finite(x *big.Rat) bool

Finite returns true if x has a finite decimal representation. x is finite if the Denom can be represented as (2**x) * (5**y).

Example

x, _ := new(big.Rat).SetString("0.125")
fmt.Println(Finite(x))
fmt.Println(Finite(big.NewRat(2, 3)))

Output:

true
false

func FinitePrec

func FinitePrec(x *big.Rat) int

FinitePrec returns the precision of the finite decimal representation of x. WARNING: Running this on a value that does not have a finite decimal representation will panic.

Example

x, _ := new(big.Rat).SetString("0.125")
fmt.Println(FinitePrec(x))

Output:

3

func FiniteString

func FiniteString(x *big.Rat) string

FiniteString returns the equivalent of x.FloatString(FinitePrec(x)). WARNING: Running this on a value that does not have a finite decimal representation will panic.

Example

x, _ := new(big.Rat).SetString("0.125")
fmt.Println(FiniteString(x))

Output:

0.125

func FiniteStringMin

func FiniteStringMin(x *big.Rat, prec int) string

FiniteStringMin returns the equivalent of x.FloatString(max(FinitePrec(x), prec)). WARNING: Running this on a value that does not have a finite decimal representation will panic.

Example

x, _ := new(big.Rat).SetString("5")
fmt.Println(FiniteStringMin(x, 2))

Output:

5.00

func Round

func Round(x *big.Rat, prec int, method RoundingMode) *big.Rat

Round sets x to its value rounded to the given precision using the given rounding mode. Returns x, which was modified in place.

Example

x, _ := new(big.Rat).SetString("0.125")
Round(x, 2, HalfEven)
fmt.Println(x.FloatString(2))

Output:

0.12

func Trunc

func Trunc(x *big.Rat, prec int) *big.Rat

Trunc sets x to the decimal value truncated at the given precision. Returns x, which was modified in place.

Example

x := big.NewRat(2, 3)
Trunc(x, 2)
fmt.Println(x.FloatString(2))

Output:

0.66

Types

type RoundingMode

type RoundingMode func(sign int, n, l *big.Int, r bool)

RoundingMode describes how to round a given number. sign is the sign of the number (needed when n is zero) n is the integer that should be rounded such that the last digit is zero. l is the current last digit of n. r indicates whether the rest of the original number, after last digit, is non-zero NOTE: This method is only called when rounding is necessary, so if l == 0 it means there was more precision that was already truncated (so r is true). For most cases you shouldn't need to implement this yourself, use one of the provided implementations in the rounding package.

var (
	// Up rounds away from zero.
	Up RoundingMode = roundUp

	// Down rounds towards zero.
	Down RoundingMode = roundDown

	// Ceil rounds towards positive infinity.
	Ceil RoundingMode = roundCeil

	// Floor rounds towards negative infinity.
	Floor RoundingMode = roundFloor

	// HalfUp rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
	HalfUp RoundingMode = roundHalfUp

	// HalfDown rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
	HalfDown RoundingMode = roundHalfDown

	// HalfEven rounds towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
	HalfEven RoundingMode = roundHalfEven
)