decimal

January 18, 2025 · View on GitHub

Package decimal implements correctly rounded decimal floating-point numbers for Go. This package is designed specifically for use in transactional financial systems.

Key Features

BSON, JSON, XML, SQL - Implements the necessary interfaces for direct compatibility with the mongo-driver/bson, encoding/json, encoding/xml, and database/sql packages.
No Heap Allocations - Optimized to avoid heap allocations, preventing garbage collector impact during arithmetic operations.
Correct Rounding - For all methods, the result is the one that would be obtained if the true mathematical value were rounded to 19 digits of precision using the half-to-even rounding (a.k.a. "banker's rounding").
No Panics - All methods are panic-free, returning errors instead of crashing your application in cases such as overflow or division by zero.
Immutability - Once set, a decimal remains constant, ensuring safe concurrent access across goroutines.
Simple String Representation - Decimals are represented in a straightforward format avoiding the complexities of scientific or engineering notations.
Rigorous Testing - All methods are cross-validated against the cockroachdb/apd and shopspring/decimal packages through extensive fuzz testing.

Getting Started

Installation

To add the decimal package to your Go workspace:

go get github.com/govalues/decimal

Basic Usage

Create decimal values using one of the constructors. After creating a decimal, you can perform various operations as shown below:

package main

import (
    "fmt"
    "github.com/govalues/decimal"
)

func main() {
    // Constructors
    d, _ := decimal.New(8, 0)               // d = 8
    e, _ := decimal.Parse("12.5")           // e = 12.5
    f, _ := decimal.NewFromFloat64(2.567)   // f = 2.567
    g, _ := decimal.NewFromInt64(7, 896, 3) // g = 7.896

    // Arithmetic operations
    fmt.Println(d.Add(e))              // 8 + 12.5
    fmt.Println(d.Sub(e))              // 8 - 12.5
    fmt.Println(d.SubAbs(e))           // abs(8 - 12.5)

    fmt.Println(d.Mul(e))              // 8 * 12.5
    fmt.Println(d.AddMul(e, f))        // 8 + 12.5 * 2.567
    fmt.Println(d.SubMul(e, f))        // 8 - 12.5 * 2.567
    fmt.Println(d.PowInt(2))           // 8²

    fmt.Println(d.Quo(e))              // 8 / 12.5
    fmt.Println(d.AddQuo(e, f))        // 8 + 12.5 / 2.567
    fmt.Println(d.SubQuo(e, f))        // 8 - 12.5 / 2.567
    fmt.Println(d.QuoRem(e))           // 8 div 12.5, 8 mod 12.5
    fmt.Println(d.Inv())               // 1 / 8

    fmt.Println(decimal.Sum(d, e, f))  // 8 + 12.5 + 2.567
    fmt.Println(decimal.Mean(d, e, f)) // (8 + 12.5 + 2.567) / 3
    fmt.Println(decimal.Prod(d, e, f)) // 8 * 12.5 * 2.567

    // Transcendental functions
    fmt.Println(e.Sqrt())              // √12.5
    fmt.Println(e.Exp())               // exp(12.5)
    fmt.Println(e.Expm1())             // exp(12.5) - 1
    fmt.Println(e.Log())               // ln(12.5)
    fmt.Println(e.Log1p())             // ln(12.5 + 1)
    fmt.Println(e.Log2())              // log₂(12.5)
    fmt.Println(e.Log10())             // log₁₀(12.5)
    fmt.Println(e.Pow(d))              // 12.5⁸

    // Rounding to 2 decimal places
    fmt.Println(g.Round(2))            // 7.90
    fmt.Println(g.Ceil(2))             // 7.90
    fmt.Println(g.Floor(2))            // 7.89
    fmt.Println(g.Trunc(2))            // 7.89

    // Conversions
    fmt.Println(f.Int64(9))            // 2 567000000
    fmt.Println(f.Float64())           // 2.567
    fmt.Println(f.String())            // 2.567

    // Formatting
    fmt.Printf("%.2f", f)              // 2.57
    fmt.Printf("%.2k", f)              // 256.70%
}

Documentation

For detailed documentation and additional examples, visit the package documentation. For examples related to financial calculations, see the money package documentation.

Comparison

Comparison with other popular packages:

Feature	govalues	cockroachdb/apd v3.2.1	shopspring/decimal v1.4.0
Correctly Rounded	Yes	No	No
Speed	High	Medium	Low¹
Heap Allocations	No	Medium	High
Precision	19 digits	Arbitrary	Arbitrary
Panic Free	Yes	Yes	No²
Mutability	Immutable	Mutable¹	Immutable
Mathematical Context	Implicit	Explicit	Implicit

Benchmarks

goos: linux
goarch: amd64
pkg: github.com/govalues/decimal-tests
cpu: AMD Ryzen 7 3700C  with Radeon Vega Mobile Gfx

Test Case	Expression	govalues	cockroachdb/apd v3.2.1	shopspring/decimal v1.4.0	govalues vs cockroachdb	govalues vs shopspring
Add	5 + 6	16.06n	74.88n	140.90n	+366.22%	+777.33%
Mul	2 * 3	16.93n	62.20n	146.00n	+267.40%	+762.37%
Quo	2 / 4 (exact)	59.52n	176.95n	657.40n	+197.30%	+1004.50%
Quo	2 / 3 (inexact)	391.60n	976.80n	2962.50n	+149.39%	+656.42%
PowInt	1. $1^{60}$	950.90n	3302.50n	4599.50n	+247.32%	+383.73%
PowInt	1. $01^{600}$	3.45µ	10.67µ	18.67µ	+209.04%	+440.89%
PowInt	1. $001^{6000}$	5.94µ	20.50µ	722.22µ	+244.88%	+12052.44%
Sqrt	√2	3.40µ	4.96µ	2101.86µ	+46.00%	+61755.71%
Exp	exp(0.5)	8.35µ	39.28µ	20.06µ	+370.58%	+140.32%
Log	ln(0.5)	54.89µ	129.01µ	151.55µ	+135.03%	+176.10%
Parse	1	16.52n	76.30n	136.55n	+362.00%	+726.82%
Parse	123.456	47.37n	176.90n	242.60n	+273.44%	+412.14%
Parse	123456789.1234567890	85.49n	224.15n	497.95n	+162.19%	+482.47%
String	1	5.11n	19.57n	198.25n	+283.21%	+3783.07%
String	123.456	35.78n	77.12n	228.85n	+115.52%	+539.51%
String	123456789.1234567890	70.72n	239.10n	337.25n	+238.12%	+376.91%
Telco	(see specification)	137.00n	969.40n	3981.00n	+607.33%	+2804.78%

The benchmark results shown in the table are provided for informational purposes only and may vary depending on your specific use case.

decimal package was created simply because shopspring/decimal was too slow and cockroachdb/apd was mutable. ↩ ↩²
shopspring/decimal panics on division by zero. ↩