dec128

package module
v1.0.2 Latest Latest
Warning

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

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

README

dec128

128-bit fixed-point decimal numbers in go.

Key Objectives

  • High performance
  • Minimal or zero memory allocation
  • High precision in financial calculations
  • 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")

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

Index

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{}

	Decimal0    = FromInt(0)
	Decimal1    = FromInt(1)
	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)

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

	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
}

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 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) Dec128

FromString creates a new Dec128 from a string.

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.

func (Dec128) Abs added in v1.0.2 

func (self Dec128) Abs() Dec128

Abs returns |d|

func (Dec128) Add 

func (self Dec128) Add(other Dec128) Dec128

Add returns the sum of the Dec128 and the other Dec128.

func (Dec128) Canonical 

func (self Dec128) Canonical() Dec128

Canonical returns a new Dec128 with the canonical representation.

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.

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) 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) IsPosistive added in v1.0.2 

func (self Dec128) IsPosistive() bool

IsPosistive 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)

func (Dec128) MarshalText 

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

func (Dec128) Mul 

func (self Dec128) Mul(other Dec128) Dec128

Mul returns self * other.

func (Dec128) Neg added in v1.0.2 

func (self Dec128) Neg() Dec128

Neg returns -d

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.

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

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) 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.

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

func (*Dec128) UnmarshalText 

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

func (Dec128) Value 

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

Source Files

View all Source files

Directories

Path Synopsis

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.