dec128

package module
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 10, 2025 License: BSD-3-Clause, MIT Imports: 7 Imported by: 0

README

dec128

GoDoc Go Report Card

128-bit fixed-point decimal numbers in go.

Key Objectives / Features

  • High performance
  • Minimal or zero memory allocation
  • Precision up to 19 decimal places
  • Fixed size memory layout (128 bits)
  • No panic or error arithmetics (use NaN instead)
  • Basic arithmetic operations required for financial calculations (specifically for banking and accounting)
  • Additional arithmetic operations for scientific calculations
  • Easy to use
  • Easy to inegrate with external systems (e.g. databases, accounting systems, JSON, etc.)
  • Financially correct rounding
  • Correct comparison of numbers encoded in different precisions (e.g. 1.0 == 1.00)
  • Correct handling of NaN values (e.g. NaN + 1 = NaN)
  • Conversion to canonical representation (e.g. 1.0000 -> 1)
  • Conversion to fixed string representation (e.g. 1.0000 -> "1.0000")
  • Conversion to human-readable string representation (e.g. 1.0000 -> "1")

Install

Run go get github.com/jokruger/dec128

Requirements

This library requires Go version >=1.23

Documentation

http://godoc.org/github.com/jokruger/dec128

Usage

package main

import (
    "fmt"
    "github.com/jokruger/dec128"
)

func main() {
    principal := dec128.FromString("1000.00")
    annualRate := dec128.FromString("5.0")
    days := 30

    dailyRate := annualRate.Div(dec128.FromInt(365))
    dailyRate = dailyRate.Div(dec128.FromInt(100))

    accruedInterest := principal.Mul(dailyRate).Mul(dec128.FromInt(days)).RoundBank(2)

    fmt.Printf("Principal: %v\n", principal.StringFixed())
    fmt.Printf("Annual Interest Rate: %v\n", annualRate.String())
    fmt.Printf("Days: %v\n", days)
    fmt.Printf("Accrued Interest: %v\n", accruedInterest.String())

    total := principal.Add(accruedInterest).RoundBank(2)
    fmt.Printf("Total after %v days: %v\n", days, total.StringFixed())
}

Why not use other libraries?

There are several other libraries that provide decimal arithmetic in Go. However, most of them are either too slow, too memory-intensive, or lack the integration features required for financial applications. This library aims to provide a high-performance, low-memory, and easy-to-use alternative to existing libraries.

Benchmarks

The following benchmarks were run on a MacBook Pro (2019) with a 2.6 GHz 6-Core Intel Core i7 processor and 16 GB of RAM (https://github.com/jokruger/go-decimal-benchmark).

                                 parse (ns/op)  string (ns/op)     add (ns/op)     mul (ns/op)     div (ns/op)

dec128.Dec128                           13.986          36.404          10.518           7.637          34.129
udecimal.Decimal                        22.383          44.740          11.998          11.141          40.701
alpacadecimal.Decimal                   90.959          83.291         222.275          70.552         481.113
shopspring.Decimal                     160.160         183.984         241.129          74.726         451.901

Notes on Terminology

  • Precision: The number of decimal places in a number. For example, 1.00 has a precision of 2 and 1.0000 has a precision of 4.
  • Expontent: Same as precision, but in the context of low-level implementation details or Dec128 encoding.
  • Canonical: The representation of a number with the minimum number of decimal places required to represent the number.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Attribution

This project includes code derived from:

  • A project licensed under the BSD 3-Clause License (Copyright © 2025 Quang).
  • A project licensed under the MIT License (Copyright © 2019 Luke Champine).

See the LICENSE file for full license texts.

Documentation

Overview

Package dec128 provides 128-bit fixed-point decimal type, operations and constants.

Index

Examples

Constants

View Source 
const MaxPrecision = uint8(uint128.MaxSafeStrLen64)

MaxPrecision is the maximum number of digits after the decimal point that can be represented. MaxPrecision = 19

View Source 
const MaxStrLen = uint128.MaxStrLen + 2

MaxStrLen is the maximum number of characters that can be in a string representation of a Dec128. MaxStrLen = uint128.MaxStrLen + dot + sign

Variables

View Source 
var (
	Zero        = Dec128{}
	One         = FromInt(1)
	NegativeOne = FromInt(-1)

	Decimal0    = Zero
	Decimal1    = One
	Decimal2    = FromInt(2)
	Decimal3    = FromInt(3)
	Decimal4    = FromInt(4)
	Decimal5    = FromInt(5)
	Decimal6    = FromInt(6)
	Decimal7    = FromInt(7)
	Decimal8    = FromInt(8)
	Decimal9    = FromInt(9)
	Decimal10   = FromInt(10)
	Decimal100  = FromInt(100)
	Decimal365  = FromInt(365)
	Decimal366  = FromInt(366)
	Decimal1000 = FromInt(1000)

	ZeroStr          = "0"
	ZeroStrBytes     = []byte(ZeroStr)
	ZeroJsonStrBytes = []byte(`"0"`)

	NaNStr          = "NaN"
	NaNStrBytes     = []byte(NaNStr)
	NaNJsonStrBytes = []byte(`"NaN"`)

	Pow10Uint64  = uint128.Pow10Uint64
	Pow10Uint128 = uint128.Pow10Uint128
)

Functions

func SetDefaultPrecision 

func SetDefaultPrecision(prec uint8)

SetDefaultPrecision sets the default precision for all Dec128 instances, where precision is the number of digits after the decimal point.

Types

type Dec128 

type Dec128 struct {
	// contains filtered or unexported fields
}

Dec128 represents a 128-bit fixed-point decimal number.

func DecodeFromUint128 

func DecodeFromUint128(coef uint128.Uint128, exp uint8) Dec128

DecodeFromUint128 decodes a Dec128 from a Uint128 and an exponent.

func DecodeFromUint64 

func DecodeFromUint64(coef uint64, exp uint8) Dec128

DecodeFromUint64 decodes a Dec128 from a uint64 and an exponent.

func FromFloat64 added in v1.0.3 

func FromFloat64(f float64) Dec128

FromFloat64 returns a decimal from float64.

func FromInt 

func FromInt(i int) Dec128

FromInt creates a new Dec128 from an int.

func FromInt64 

func FromInt64(i int64) Dec128

FromInt64 creates a new Dec128 from an int64.

func FromString 

func FromString[S string | []byte](s S) Dec128

FromString creates a new Dec128 from a string. The string must be in the format of [+-][0-9]+(.[0-9]+)? In case of empty string, it returns Zero. In case of errors, it returns NaN with the corresponding error.

Example 
a := FromString("0.123456789")
fmt.Println(a.String())

Output:

0.123456789

func NaN 

func NaN(reason errors.Error) Dec128

NaN returns a Dec128 with the given error.

func New 

func New(coef uint128.Uint128, exp uint8, neg bool) Dec128

New creates a new Dec128 from a uint64 coefficient, uint8 exponent, and negative flag. In case of errors it returns NaN with the error.

func (Dec128) Abs added in v1.0.2 

func (self Dec128) Abs() Dec128

Abs returns |d| If Dec128 is NaN, the result will be NaN.

Example 
a := FromString("-123.45")
fmt.Println(a.Abs())

Output:

123.45

func (Dec128) Add 

func (self Dec128) Add(other Dec128) Dec128

Add returns the sum of the Dec128 and the other Dec128. If any of the Dec128 is NaN, the result will be NaN. In case of overflow, the result will be NaN.

Example 
a := FromString("123.45")
b := FromString("678.90")
fmt.Println(a.Add(b))

Output:

802.35

func (Dec128) Canonical 

func (self Dec128) Canonical() Dec128

Canonical returns a new Dec128 with the canonical representation. If the Dec128 is NaN, it returns itself.

func (Dec128) Coefficient 

func (self Dec128) Coefficient() uint128.Uint128

Coefficient returns the coefficient of the Dec128.

func (Dec128) Compare 

func (self Dec128) Compare(other Dec128) int

Compare returns -1 if the Dec128 is less than the other Dec128, 0 if they are equal, and 1 if the Dec128 is greater than the other Dec128. NaN is considered less than any valid Dec128.

func (Dec128) Copy added in v1.0.2 

func (self Dec128) Copy() Dec128

Copy returns a copy of the Dec128.

func (Dec128) Div 

func (self Dec128) Div(other Dec128) Dec128

Div returns self / other. If any of the Dec128 is NaN, the result will be NaN. In case of overflow, underflow, or division by zero, the result will be NaN.

Example 
a := FromString("1")
b := FromString("3")
fmt.Println(a.Div(b))

Output:

0.3333333333333333333

func (Dec128) EncodeToUint128 

func (self Dec128) EncodeToUint128(exp uint8) (uint128.Uint128, error)

EncodeToUint128 returns the Dec128 encoded as uint128 coefficient with requested exponent. Negative values are not allowed.

func (Dec128) EncodeToUint64 

func (self Dec128) EncodeToUint64(exp uint8) (uint64, error)

EncodeToUint64 returns the Dec128 encoded as uint64 coefficient with requested exponent. Negative and too large values are not allowed.

func (Dec128) Equal 

func (self Dec128) Equal(other Dec128) bool

Equal returns true if the Dec128 is equal to the other Dec128.

func (Dec128) ErrorDetails 

func (self Dec128) ErrorDetails() error

ErrorDetails returns the error details of the Dec128. If the Dec128 is not NaN, it returns nil.

func (Dec128) Exponent 

func (self Dec128) Exponent() uint8

Exponent returns the exponent of the Dec128.

func (Dec128) GreaterThan added in v1.0.2 

func (self Dec128) GreaterThan(other Dec128) bool

GreaterThan returns true if the Dec128 is greater than the other Dec128.

func (Dec128) GreaterThanOrEqual added in v1.0.2 

func (self Dec128) GreaterThanOrEqual(other Dec128) bool

GreaterThanOrEqual returns true if the Dec128 is greater than or equal to the other Dec128.

func (Dec128) InexactFloat64 added in v1.0.3 

func (self Dec128) InexactFloat64() (float64, error)

InexactFloat64 returns the float64 representation of the decimal. The result may not be 100% accurate due to the limitation of float64 (less decimal precision).

func (Dec128) Int added in v1.0.3 

func (self Dec128) Int() (int, error)

Int returns the integer part of the Dec128 as int.

func (Dec128) Int64 added in v1.0.3 

func (self Dec128) Int64() (int64, error)

Int64 returns the integer part of the Dec128 as int64.

func (Dec128) IsNaN 

func (self Dec128) IsNaN() bool

IsNaN returns true if the Dec128 is NaN.

func (Dec128) IsNegative added in v1.0.2 

func (self Dec128) IsNegative() bool

IsNegative returns true if the Dec128 is negative and false otherwise. If the Dec128 is NaN, it returns false.

func (Dec128) IsPositive added in v1.0.4 

func (self Dec128) IsPositive() bool

IsPositive returns true if the Dec128 is positive and false otherwise. If the Dec128 is NaN, it returns false.

func (Dec128) IsZero 

func (self Dec128) IsZero() bool

IsZero returns true if the Dec128 is zero. If the Dec128 is NaN, it returns false.

func (Dec128) LessThan added in v1.0.2 

func (self Dec128) LessThan(other Dec128) bool

LessThan returns true if the Dec128 is less than the other Dec128.

func (Dec128) LessThanOrEqual added in v1.0.2 

func (self Dec128) LessThanOrEqual(other Dec128) bool

LessThanOrEqual returns true if the Dec128 is less than or equal to the other Dec128.

func (Dec128) MarshalJSON 

func (self Dec128) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (Dec128) MarshalText 

func (self Dec128) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (Dec128) Mul 

func (self Dec128) Mul(other Dec128) Dec128

Mul returns self * other. If any of the Dec128 is NaN, the result will be NaN. In case of overflow, the result will be NaN.

Example 
a := FromString("123.45")
b := FromString("678.90")
fmt.Println(a.Mul(b))

Output:

83810.205

func (Dec128) Neg added in v1.0.2 

func (self Dec128) Neg() Dec128

Neg returns -d If Dec128 is NaN, the result will be NaN.

func (Dec128) Precision 

func (self Dec128) Precision() uint8

Precision returns the precision of the Dec128.

func (Dec128) Rescale 

func (self Dec128) Rescale(prec uint8) Dec128

Rescale returns a new Dec128 with the given precision. If the Dec128 is NaN, it returns itself. In case of errors it returns NaN with the error.

func (Dec128) RoundAwayFromZero 

func (self Dec128) RoundAwayFromZero(prec uint8) Dec128

RoundAwayFromZero rounds the decimal to the specified prec using Away From Zero method (https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero).

Examples: 

RoundAwayFromZero(1.236, 2) = 1.24
RoundAwayFromZero(1.235, 2) = 1.24
RoundAwayFromZero(1.234, 2) = 1.24
RoundAwayFromZero(-1.234, 2) = -1.24
RoundAwayFromZero(-1.235, 2) = -1.24
RoundAwayFromZero(-1.236, 2) = -1.24

func (Dec128) RoundBank 

func (self Dec128) RoundBank(prec uint8) Dec128

RoundBank uses half up to even (banker's rounding) to round the decimal to the specified precision.

Examples: 

RoundBank(2.121, 2) = 2.12 ; rounded down
RoundBank(2.125, 2) = 2.12 ; rounded down, rounding digit is an even number
RoundBank(2.135, 2) = 2.14 ; rounded up, rounding digit is an odd number
RoundBank(2.1351, 2) = 2.14; rounded up
RoundBank(2.127, 2) = 2.13 ; rounded up

func (Dec128) RoundDown 

func (self Dec128) RoundDown(prec uint8) Dec128

RoundDown (or Floor) rounds the decimal to the specified precision using Round Down method (https://en.wikipedia.org/wiki/Rounding#Rounding_down).

Examples: 

RoundDown(1.236, 2) = 1.23
RoundDown(1.235, 2) = 1.23
RoundDown(1.234, 2) = 1.23
RoundDown(-1.234, 2) = -1.24
RoundDown(-1.235, 2) = -1.24
RoundDown(-1.236, 2) = -1.24

func (Dec128) RoundHalfAwayFromZero 

func (self Dec128) RoundHalfAwayFromZero(prec uint8) Dec128

RoundHalfAwayFromZero rounds the decimal to the specified prec using Half Away from Zero method (https://en.wikipedia.org/wiki/Rounding#Rounding_half_away_from_zero).

Examples: 

RoundHalfAwayFromZero(1.236, 2) = 1.24
RoundHalfAwayFromZero(1.235, 2) = 1.24
RoundHalfAwayFromZero(1.234, 2) = 1.23
RoundHalfAwayFromZero(-1.234, 2) = -1.23
RoundHalfAwayFromZero(-1.235, 2) = -1.24
RoundHalfAwayFromZero(-1.236, 2) = -1.24

func (Dec128) RoundHalfTowardZero 

func (self Dec128) RoundHalfTowardZero(prec uint8) Dec128

RoundHalfTowardZero rounds the decimal to the specified prec using Half Toward Zero method (https://en.wikipedia.org/wiki/Rounding#Rounding_half_toward_zero).

Examples: 

RoundHalfTowardZero(1.236, 2) = 1.24
RoundHalfTowardZero(1.235, 2) = 1.23
RoundHalfTowardZero(1.234, 2) = 1.23
RoundHalfTowardZero(-1.234, 2) = -1.23
RoundHalfTowardZero(-1.235, 2) = -1.23
RoundHalfTowardZero(-1.236, 2) = -1.24

func (Dec128) RoundTowardZero 

func (self Dec128) RoundTowardZero(prec uint8) Dec128

RoundTowardZero rounds the decimal to the specified prec using Toward Zero method (https://en.wikipedia.org/wiki/Rounding#Rounding_toward_zero).

Examples: 

RoundTowardZero(1.236, 2) = 1.23
RoundTowardZero(1.235, 2) = 1.23
RoundTowardZero(1.234, 2) = 1.23
RoundTowardZero(-1.234, 2) = -1.23
RoundTowardZero(-1.235, 2) = -1.23
RoundTowardZero(-1.236, 2) = -1.23

func (Dec128) RoundUp 

func (self Dec128) RoundUp(prec uint8) Dec128

RoundUp (or Ceil) rounds the decimal to the specified precision using Round Up method (https://en.wikipedia.org/wiki/Rounding#Rounding_up).

Examples: 

RoundUp(1.236, 2) = 1.24
RoundUp(1.235, 2) = 1.24
RoundUp(1.234, 2) = 1.24
RoundUp(-1.234, 2) = -1.23
RoundUp(-1.235, 2) = -1.23
RoundUp(-1.236, 2) = -1.23

func (*Dec128) Scan 

func (self *Dec128) Scan(src any) error

Scan implements the sql.Scanner interface.

func (Dec128) Sign 

func (self Dec128) Sign() int

Sign returns -1 if the Dec128 is negative, 0 if it is zero, and 1 if it is positive.

func (Dec128) Sqrt added in v1.0.5 

func (self Dec128) Sqrt() Dec128

Sqrt returns the square root of the Dec128. If Dec128 is NaN, the result will be NaN. If Dec128 is negative, the result will be NaN. In case of overflow, the result will be NaN.

Example 
a := FromString("4")
fmt.Println(a.Sqrt())

Output:

2

func (Dec128) String 

func (self Dec128) String() string

String returns the string representation of the Dec128 with the trailing zeros removed. If the Dec128 is zero, the string "0" is returned. If the Dec128 is NaN, the string "NaN" is returned.

func (Dec128) StringFixed 

func (self Dec128) StringFixed() string

StringFixed returns the string representation of the Dec128 with the trailing zeros preserved. If the Dec128 is NaN, the string "NaN" is returned.

func (Dec128) Sub 

func (self Dec128) Sub(other Dec128) Dec128

Sub returns the difference of the Dec128 and the other Dec128. If any of the Dec128 is NaN, the result will be NaN. In case of overflow/underflow, the result will be NaN.

Example 
a := FromString("123.45")
b := FromString("678.90")
fmt.Println(a.Sub(b))

Output:

-555.45

func (Dec128) Trunc 

func (self Dec128) Trunc(prec uint8) Dec128

Trunc returns 'self' after truncating the decimal to the specified precision.

Examples: 

Trunc(1.12345, 4) = 1.1234
Trunc(1.12335, 4) = 1.1233

func (*Dec128) UnmarshalJSON 

func (self *Dec128) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (*Dec128) UnmarshalText 

func (self *Dec128) UnmarshalText(data []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (Dec128) Value 

func (self Dec128) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

Source Files

View all Source files

Directories

Path Synopsis
Package errors provides custom error type and error codes for uint128 and dec128 packages.
 Package errors provides custom error type and error codes for uint128 and dec128 packages.
Package uint128 provides 128-bit unsigned integer type and basic operations.
 Package uint128 provides 128-bit unsigned integer type and basic operations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.