udecimal

package module

v1.2.0 Latest Latest Go to latest Published: Oct 16, 2024 License: MIT Imports: 12 Imported by: 16

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/quagmt/udecimal

Links

Open Source Insights

README ¶

udecimal

High performance, high precision, zero allocation fixed-point decimal number for financial applications.

Installation

go get github.com/quagmt/udecimal

Features

High Precision: Supports up to 19 decimal places with no precision loss during arithmetic operations.
Optimized for Speed: Designed for high performance with zero memory allocation in most cases (see Benchmarks and How it works).
Panic-Free: All errors are returned as values, ensuring no unexpected panics.
Immutable: All arithmetic operations return a new Decimal value, preserving the original value and safe for concurrent use.
Versatile Rounding Methods: Includes HALF AWAY FROM ZERO, HALF TOWARD ZERO, and Banker's rounding.

NOTE: This library does not perform implicit rounding. If the result of an operation exceeds the maximum precision, extra digits are truncated. All rounding methods must be explicitly invoked. (see Rounding Methods for more details)

Documentation

Checkout documentation for more information.

Usage

package main

import (
	"fmt"

	"github.com/quagmt/udecimal"
)

func main() {
	// Create a new decimal number
	a, _ := udecimal.NewFromInt64(123456, 3)              // a = 123.456
	b, _ := udecimal.NewFromInt64(-123456, 4)             // b = -12.3456
	c, _ := udecimal.NewFromFloat64(1.2345)               // c = 1.2345
	d, _ := udecimal.Parse("4123547.1234567890123456789") // d = 4123547.1234567890123456789

	// Basic arithmetic operations
	fmt.Println(a.Add(b)) // 123.456 - 12.3456 = 111.1104
	fmt.Println(a.Sub(b)) // 123.456 + 12.3456 = 135.8016
	fmt.Println(a.Mul(b)) // 123.456 * -12.3456 = -1524.1383936
	fmt.Println(a.Div(b)) // 123.456 / -12.3456 = -10
	fmt.Println(a.Div(d)) // 123.456 / 4123547.1234567890123456789 = 0.0000299392722585176

	// Rounding
	fmt.Println(c.RoundBank(3)) // banker's rounding: 1.2345 -> 1.234
	fmt.Println(c.RoundHAZ(3))  // half away from zero: 1.2345 -> 1.235
	fmt.Println(c.RoundHTZ(3))  // half towards zero: 1.2345 -> 1.234
	fmt.Println(c.Trunc(2))     // truncate: 1.2345 -> 1.23
	fmt.Println(c.Floor())      // floor: 1.2345 -> 1
	fmt.Println(c.Ceil())       // ceil: 1.2345 -> 2

	// Display
	fmt.Println(a.String())         // 123.456
	fmt.Println(a.StringFixed(10))  // 123.4560000000
	fmt.Println(a.InexactFloat64()) // 123.456
}

Why another decimal library?

There are already a couple of decimal libraries available in Go, such as shopspring/decimal, cockroachdb/apd, govalues/decimal, etc. However, each of these libraries has its own limitations, for example:

shopspring/decimal is great for general-purpose decimal arithmetic because of arbitrary precision. However, it's slow and requires memory allocation for every arithmetic operation. Also in financial applications, arbitrary precision is not always necessary.
cockroachdb/apd is faster but still requires memory allocation. Also the API is not very intuitive.
govalues/decimal is fast, no memory allocation, easy to use but the data range is only limited to 19 digits (include both the integer and fractional parts). Some operations (especially Quo/QuoRem) usually overflow and fallback to use big.Int API, which hurts the performance. Another limitation is that it starts losing precision when the total number of digits exceeds 19.

This library is designed to address these limitations, providing both high performance and zero allocation while maintaining an acceptable range of precision, which is suitable for most financial applications.

Rounding Methods

Rounding numbers can often be challenging and confusing due to the variety of methods available. Each method serves specific purposes, and it's common for developers to make mistakes or incorrect assumptions about how rounding should be performed. For example, the result of round(1.45) could be either 1.4 or 1.5, depending on the rounding method used.

This issue is particularly critical in financial applications, where even minor rounding errors can accumulate and lead to significant financial losses. To mitigate such errors, this library intentionally avoids implicit rounding. If the result of an operation exceeds the maximum precision specified by developers beforehand, extra digits are truncated. Developers need to explicitly choose the rounding method they want to use. The supported rounding methods are:

Banker's rounding or round half to even
Half away from zero (HAZ)
Half toward zero (HTZ)

Examples:

package main

import (
	"fmt"

	"github.com/quagmt/udecimal"
)

func main() {
	// Create a new decimal number
	a, _ := udecimal.NewFromFloat64(1.45) // a = 1.45

	// Rounding
	fmt.Println(a.RoundBank(1)) // banker's rounding: 1.45 -> 1.4
	fmt.Println(a.RoundHAZ(1))  // half away from zero: 1.45 -> 1.5
	fmt.Println(a.RoundHTZ(1))  // half towards zero: 1.45 -> 1.4
}

How it works

As mentioned above, this library is not always memory allocation free. However, those cases where we need to allocate memory are incredily rare. To understand why, let's take a look at how the Decimal type is implemented.

The Decimal type represents a fixed-point decimal number. It consists of three components: sign, coefficient, and prec. The number is represented as:

// decimal value = (neg == true ? -1 : 1) * coef * 10^(-prec)
type Decimal struct {
	coef bint
	neg bool
	prec uint8 // 0 <= prec <= 19
}

// Example:
// 123.456 = 123456 * 10^-3
// -> neg = false, coef = 123456, prec = 3

// -123.456 = -123456 / 10^-3
// -> neg = true, coef = 123456, prec = 3

You can notice that coef data type is bint, which is a custom data type:

type bint struct {
	// For coefficients exceeding u128
	bigInt *big.Int

	// For coefficients less than 2^128-1
	u128 u128
}

The bint type can store coefficients up to 2^128 - 1 using u128. Arithmetic operations with u128 are fast and require no memory allocation. If result of an arithmetic operation exceeds u128 capacity, the whole operation will be performed using big.Int API. Such operations are slower and do involve memory allocation. However, those cases are rare in financial applications due to the extensive range provided by a 128-bit unsigned integer, for example:

If precision is 0, the decimal range it can store is: [-340282366920938463463374607431768211455, 340282366920938463463374607431768211455](approximately -340 to 340 undecillion)
If precision is 19, the decimal range becomes: [-34028236692093846346.3374607431768211455, 34028236692093846346.3374607431768211455] (approximately -34 to 34 quintillion)

Therefore, in most cases you can expect high performance and no memory allocation when using this library.

Credits

This library is inspired by govalues/decimal and lukechampine/uint128

License

MIT

Documentation ¶

Overview ¶

Package udecimal provides a high-performance, high-precision (up to 19 digits after the decimal point) decimal arithmetic library. It includes functions for parsing and performing arithmetic operations such as addition, subtraction, multiplication, and division on decimal numbers. The package is designed to handle decimal numbers with a high degree of precision and efficiency, making it suitable for high-traffic financial applications where both precision and performance are critical.

Maximum and default precision is 19 digits after the decimal point. The default precision can be changed globally to any value between 1 and 19 to suit your use case and make sure that the precision is consistent across the entire application. See SetDefaultPrecision for more details.

Codec ¶

The udecimal package supports various encoding and decoding mechanisms to facilitate easy integration with different data storage and transmission systems.

Marshal/UnmarshalJSON
Marshal/UnmarshalBinary: gob, protobuf
SQL: The Decimal type implements the sql.Scanner interface, enabling seamless integration with SQL databases.

For more details, see the documentation for each method.

Index ¶

Variables
func SetDefaultPrecision(prec uint8)
type Decimal
type NullDecimal
- func (d *NullDecimal) Scan(src any) error
- func (d NullDecimal) Value() (driver.Value, error)

Constants ¶

This section is empty.

Variables ¶

View Source

var (

	// ErrPrecOutOfRange is returned when the decimal precision is greater than the default precision
	// default precision can be configured using SetDefaultPrecision, and its value is up to 19
	ErrPrecOutOfRange = fmt.Errorf("precision out of range. Only support maximum %d digits after the decimal point", defaultPrec)

	// ErrEmptyString is returned when the input string is empty
	ErrEmptyString = fmt.Errorf("parse empty string")

	// ErrMaxStrLen is returned when the input string exceeds the maximum length
	// This limitation is set to prevent large string input which can cause performance issue
	// Maximum length is set to 200
	ErrMaxStrLen = fmt.Errorf("string input exceeds maximum length %d", maxStrLen)

	// ErrInvalidFormat is returned when the input string is not in the correct format
	// It doesn't support scientific notation, such as 1e-2, 1.23e4, etc.
	ErrInvalidFormat = fmt.Errorf("invalid format")

	// ErrDivideByZero is returned when dividing by zero
	ErrDivideByZero = fmt.Errorf("can't divide by zero")

	// ErrSqrtNegative is returned when calculating square root of negative number
	ErrSqrtNegative = fmt.Errorf("can't calculate square root of negative number")

	// ErrInvalidBinaryData is returned when unmarshalling invalid binary data
	// The binary data should follow the format as described in MarshalBinary
	ErrInvalidBinaryData = fmt.Errorf("invalid binary data")
)

View Source

var (
	Zero = Decimal{}
	One  = MustFromInt64(1, 0)
)

Functions ¶

func SetDefaultPrecision ¶

func SetDefaultPrecision(prec uint8)

SetDefaultPrecision changes the default precision for decimal numbers in the package. Max precision is 19 and is also default.

This function is particularly useful when you want to have your precision of the deicmal smaller than 19 across the whole application. It should be called only once at the beginning of your application

Panics if the new precision is greater than 19 (maxPrec) or new precision is 0

Example ¶

SetDefaultPrecision(10)
defer SetDefaultPrecision(19)

a := MustParse("1.23")
b := MustParse("4.12475")
c, _ := a.Div(b)
fmt.Println(c)

Output:
0.2981998909

Types ¶

type Decimal ¶

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

Decimal represents a fixed-point decimal number. The number is represented as a struct with three fields: coef, neg, and prec.

coef: the coefficient of the decimal number
neg: true if the number is negative
prec: the number of digits after the decimal point (0 to 19)

Decimal numbers are immutable and can be used in arithmetic operations such as addition, subtraction, multiplication, and division.

func MustFromFloat64 ¶

func MustFromFloat64(f float64) Decimal

MustFromFloat64 similars to NewFromFloat64, but panics instead of returning error

Example ¶

fmt.Println(MustFromFloat64(1.234))

// cautious: result will lose some precision when converting to decimal
fmt.Println(MustFromFloat64(123456789.1234567890123456789))

Output:
1.234
123456789.12345679

func MustFromInt64 ¶

func MustFromInt64(coef int64, prec uint8) Decimal

MustFromInt64 similars to NewFromInt64, but panics instead of returning error

Example ¶

fmt.Println(MustFromInt64(123, 3))
fmt.Println(MustFromInt64(-12345, 2))

Output:
0.123
-123.45

func MustFromUint64 ¶

func MustFromUint64(coef uint64, prec uint8) Decimal

MustFromUint64 similars to NewFromUint64, but panics instead of returning error

Example ¶

fmt.Println(MustFromUint64(123, 3))
fmt.Println(MustFromUint64(12345, 2))

Output:
0.123
123.45

func MustParse ¶

func MustParse(s string) Decimal

MustParse similars to Parse, but pacnis instead of returning error.

Example ¶

fmt.Println(MustParse("1234567890123456789.1234567890123456789"))
fmt.Println(MustParse("-1234567890123456789.1234567890123456789"))
fmt.Println(MustParse("-0.00007890123456789"))

Output:
1234567890123456789.1234567890123456789
-1234567890123456789.1234567890123456789
-0.00007890123456789

func NewFromFloat64 ¶

func NewFromFloat64(f float64) (Decimal, error)

NewFromFloat64 returns decimal from float64.

**NOTE**: you'll expect to lose some precision for this method due to FormatFloat. See: https://github.com/golang/go/issues/29491

This method is only suitable for small numbers with low precision. e.g. 1.0001, 0.0001, -123.456, -1000000.123456. You should avoid using this method if your input number has high precision.

Returns error when:

f is NaN or Inf
error when parsing float to string and then to decimal

Example ¶

fmt.Println(NewFromFloat64(1.234))

// cautious: result will lose some precision when converting to decimal
fmt.Println(NewFromFloat64(123456789.1234567890123456789))

Output:
1.234 <nil>
123456789.12345679 <nil>

func NewFromHiLo ¶

func NewFromHiLo(neg bool, hi uint64, lo uint64, prec uint8) (Decimal, error)

NewFromHiLo returns Decimal from 128-bit unsigned integer (hi,lo)

Example ¶

fmt.Println(NewFromHiLo(false, 1, 1, 10))
fmt.Println(NewFromHiLo(true, 0, 123456, 4))

Output:
1844674407.3709551617 <nil>
-12.3456 <nil>

func NewFromInt64 ¶

func NewFromInt64(coef int64, prec uint8) (Decimal, error)

NewFromInt64 returns a decimal which equals to coef / 10^prec and coef is an int64. Trailing zeros wll be removed and the prec will also be adjusted

Example ¶

fmt.Println(NewFromInt64(123, 3))
fmt.Println(NewFromInt64(12345, 20))

Output:
0.123 <nil>
0 precision out of range. Only support maximum 19 digits after the decimal point

func NewFromUint64 ¶

func NewFromUint64(coef uint64, prec uint8) (Decimal, error)

NewFromUint64 returns a decimal which equals to coef / 10^prec and coef is an uint64 Trailing zeros wll be removed and the prec will also be adjusted

Example ¶

fmt.Println(NewFromUint64(123, 3))
fmt.Println(NewFromUint64(12345, 2))
fmt.Println(NewFromUint64(12345, 20))

Output:
0.123 <nil>
123.45 <nil>
0 precision out of range. Only support maximum 19 digits after the decimal point

func Parse ¶

func Parse(s string) (Decimal, error)

Parse parses a number in string to Decimal. The string must be in the format of: [+-]d{1,19}[.d{1,19}]

Returns error if:

empty/invalid string
the number has more than 19 digits after the decimal point

Example ¶

fmt.Println(Parse("1234567890123456789.1234567890123456789"))
fmt.Println(Parse("-1234567890123456789.1234567890123456789"))
fmt.Println(Parse("-0.00007890123456789"))

// error cases
fmt.Println(Parse("0.12345678901234567890123"))
fmt.Println(Parse(""))
fmt.Println(Parse("1.123.123"))

Output:
1234567890123456789.1234567890123456789 <nil>
-1234567890123456789.1234567890123456789 <nil>
-0.00007890123456789 <nil>
0 precision out of range. Only support maximum 19 digits after the decimal point
0 parse empty string
0 invalid format: can't parse '1.123.123' to Decimal

func (Decimal) Abs ¶

func (d Decimal) Abs() Decimal

Abs returns |d|

Example ¶

fmt.Println(MustParse("-123.45").Abs())

Output:
123.45

func (Decimal) Add ¶

func (d Decimal) Add(e Decimal) Decimal

Add returns d + e

Example ¶

a := MustParse("1.23")
b := MustParse("4.12475")
c := a.Add(b)
fmt.Println(c)

Output:
5.35475

func (Decimal) Add64 ¶

func (d Decimal) Add64(e uint64) Decimal

Add64 returns d + e where e is a uint64

Example ¶

a := MustParse("1.23")
c := a.Add64(4)
fmt.Println(c)

Output:
5.23

func (Decimal) Ceil ¶

func (d Decimal) Ceil() Decimal

Ceil returns the smallest integer value greater than or equal to d.

Example ¶

fmt.Println(MustParse("1.23").Ceil())

Output:
2

func (Decimal) Cmp ¶

func (d Decimal) Cmp(e Decimal) int

Cmp compares two decimals d,e and returns:

-1 if d < e
 0 if d == e
+1 if d > e

Example ¶

fmt.Println(MustParse("1.23").Cmp(MustParse("4.12475")))
fmt.Println(MustParse("1.23").Cmp(MustParse("1.23")))
fmt.Println(MustParse("1.23").Cmp(MustParse("0.12475")))

Output:
-1
0
1

func (Decimal) Div ¶

func (d Decimal) Div(e Decimal) (Decimal, error)

Div returns d / e. If the result has more than 19 fraction digits, it will be truncated to 19 digits.

Returns divide by zero error when e is zero

Example ¶

fmt.Println(MustParse("1.23").Div(MustParse("4.12475")))
fmt.Println(MustParse("1.23").Div(MustParse("0")))

Output:
0.2981998909024789381 <nil>
0 can't divide by zero

func (Decimal) Div64 ¶

func (d Decimal) Div64(v uint64) (Decimal, error)

Div64 returns d / e where e is a uint64. If the result has more than 19 fraction digits, it will be truncated to 19 digits.

Returns divide by zero error when e is zero

Example ¶

fmt.Println(MustParse("1.23").Div64(4))
fmt.Println(MustParse("1.23").Div64(0))

Output:
0.3075 <nil>
0 can't divide by zero

func (Decimal) Equal ¶ added in v1.2.0

func (d Decimal) Equal(e Decimal) bool

Equal reports whether the two decimals d and e are equal.

Example ¶

fmt.Println(MustParse("1.123").Equal(MustParse("-1.123")))
fmt.Println(MustParse("1.123").Equal(MustParse("1.1230000")))

Output:
false
true

func (Decimal) Floor ¶

func (d Decimal) Floor() Decimal

Floor returns the largest integer value less than or equal to d.

Example ¶

fmt.Println(MustParse("1.23").Floor())
fmt.Println(MustParse("-1.23").Floor())

Output:
1
-2

func (Decimal) InexactFloat64 ¶

func (d Decimal) InexactFloat64() float64

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

Caution: this method will not return the exact number if the decimal is too large.

e.g. 123456789012345678901234567890123456789.9999999999999999999 -> 123456789012345680000000000000000000000

Example ¶

fmt.Println(MustParse("1.23").InexactFloat64())
fmt.Println(MustParse("123456789.123456789").InexactFloat64())

Output:
1.23
1.2345678912345679e+08

func (Decimal) IsNeg ¶

func (d Decimal) IsNeg() bool

IsNeg returns

true if d < 0
false if d >= 0

Example ¶

fmt.Println(MustParse("1.23").IsNeg())
fmt.Println(MustParse("-1.23").IsNeg())
fmt.Println(MustParse("0").IsNeg())

Output:
false
true
false

func (Decimal) IsPos ¶

func (d Decimal) IsPos() bool

IsPos returns

true if d > 0
false if d <= 0

Example ¶

fmt.Println(MustParse("1.23").IsPos())
fmt.Println(MustParse("-1.23").IsPos())
fmt.Println(MustParse("0").IsPos())

Output:
true
false
false

func (Decimal) IsZero ¶

func (d Decimal) IsZero() bool

IsZero returns

true if d == 0
false if d != 0

Example ¶

fmt.Println(MustParse("1.23").IsZero())
fmt.Println(MustParse("0").IsZero())

Output:
false
true

func (Decimal) MarshalBinary ¶

func (d Decimal) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler interface with custom binary format.

Binary format: [overflow + neg] [prec] [total bytes] [coef]

 example 1: -1.2345
 1st byte: 0b0001_0000 (overflow = true, neg = false)
 2nd byte: 0b0000_0100 (prec = 4)
 3rd byte: 0b0000_1101 (total bytes = 11)
 4th-11th bytes: 0x0000_0000_0000_3039 (coef = 12345, only stores the coef.lo part)

 example 2: 1234567890123456789.1234567890123456789
 1st byte: 0b0000_0000 (overflow = false, neg = false)
 2nd byte: 0b0001_0011 (prec = 19)
 3rd byte: 0b0001_0011 (total bytes = 19)
 4th-11th bytes: 0x0949_b0f6_f002_3313 (coef.hi)
 12th-19th bytes: 0xd3b5_05f9_b5f1_8115 (coef.lo)

Example ¶

fmt.Println(MustParse("1.23").MarshalBinary())
fmt.Println(MustParse("-1.2345").MarshalBinary())
fmt.Println(MustParse("1234567890123456789.1234567890123456789").MarshalBinary())

Output:
[0 2 11 0 0 0 0 0 0 0 123] <nil>
[1 4 11 0 0 0 0 0 0 48 57] <nil>
[0 19 19 9 73 176 246 240 2 51 19 211 181 5 249 181 241 129 21] <nil>

func (Decimal) MarshalJSON ¶

func (d Decimal) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

Example ¶

a, _ := MustParse("1.23").MarshalJSON()
b, _ := MustParse("-1.2345").MarshalJSON()
c, _ := MustParse("1234567890123456789.1234567890123456789").MarshalJSON()
fmt.Println(string(a))
fmt.Println(string(b))
fmt.Println(string(c))

Output:
"1.23"
"-1.2345"
"1234567890123456789.1234567890123456789"

func (Decimal) MarshalText ¶ added in v1.2.0

func (d Decimal) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

Example ¶

a, _ := MustParse("1.23").MarshalText()
b, _ := MustParse("-1.2345").MarshalText()
c, _ := MustParse("1234567890123456789.1234567890123456789").MarshalText()
fmt.Println(string(a))
fmt.Println(string(b))
fmt.Println(string(c))

Output:
1.23
-1.2345
1234567890123456789.1234567890123456789

func (Decimal) Mul ¶

func (d Decimal) Mul(e Decimal) Decimal

Mul returns d * e. The result will have at most defaultPrec digits after the decimal point.

Example ¶

a := MustParse("1.23")
b := MustParse("4.12475")
c := a.Mul(b)
fmt.Println(c)

Output:
5.0734425

func (Decimal) Mul64 ¶

func (d Decimal) Mul64(v uint64) Decimal

Mul64 returns d * e where e is a uint64. The result will have at most defaultPrec digits after the decimal point.

Example ¶

a := MustParse("1.23")
c := a.Mul64(4)
fmt.Println(c)

Output:
4.92

func (Decimal) Neg ¶

func (d Decimal) Neg() Decimal

Neg returns -d

Example ¶

fmt.Println(MustParse("1.23").Neg())
fmt.Println(MustParse("-1.23").Neg())

Output:
-1.23
1.23

func (Decimal) PowInt ¶

func (d Decimal) PowInt(e int) Decimal

PowInt returns d^e where e is an integer.

Examples:

PowInt(2.5, 2) = 6.25
PowInt(2.5, -2) = 0.16

Example ¶

fmt.Println(MustParse("1.23").PowInt(2))
fmt.Println(MustParse("1.23").PowInt(0))
fmt.Println(MustParse("1.23").PowInt(-2))

Output:
1.5129
1
0.6609822195782933439

func (Decimal) Prec ¶

func (d Decimal) Prec() int

Prec returns decimal precision

Example ¶

fmt.Println(MustParse("1.23").Prec())

Output:
2

func (Decimal) RoundBank ¶

func (d Decimal) RoundBank(prec uint8) Decimal

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

Examples:

RoundBank(1.12345, 4) = 1.1234
RoundBank(1.12335, 4) = 1.1234
RoundBank(1.5, 0) = 2
RoundBank(-1.5, 0) = -2

Example ¶

fmt.Println(MustParse("1.12345").RoundBank(4))
fmt.Println(MustParse("1.12335").RoundBank(4))
fmt.Println(MustParse("1.5").RoundBank(0))
fmt.Println(MustParse("-1.5").RoundBank(0))

Output:
1.1234
1.1234
2
-2

func (Decimal) RoundHAZ ¶

func (d Decimal) RoundHAZ(prec uint8) Decimal

RoundHAZ 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:

Round(1.12345, 4) = 1.1235
Round(1.12335, 4) = 1.1234
Round(1.5, 0) = 2
Round(-1.5, 0) = -2

Example ¶

fmt.Println(MustParse("1.12345").RoundHAZ(4))
fmt.Println(MustParse("1.12335").RoundHAZ(4))
fmt.Println(MustParse("1.5").RoundHAZ(0))
fmt.Println(MustParse("-1.5").RoundHAZ(0))

Output:
1.1235
1.1234
2
-2

func (Decimal) RoundHTZ ¶

func (d Decimal) RoundHTZ(prec uint8) Decimal

RoundHTZ rounds the decimal to the specified prec using HALF TOWARD ZERO method (https://en.wikipedia.org/wiki/Rounding#Rounding_half_toward_zero).

Examples:

Round(1.12345, 4) = 1.1234
Round(1.12335, 4) = 1.1233
Round(1.5, 0) = 1
Round(-1.5, 0) = -1

Example ¶

fmt.Println(MustParse("1.12345").RoundHTZ(4))
fmt.Println(MustParse("1.12335").RoundHTZ(4))
fmt.Println(MustParse("1.5").RoundHTZ(0))
fmt.Println(MustParse("-1.5").RoundHTZ(0))

Output:
1.1234
1.1233
1
-1

func (*Decimal) Scan ¶

func (d *Decimal) Scan(src any) error

Scan implements sql.Scanner interface.

Example ¶

var a Decimal
_ = a.Scan("1.23")
fmt.Println(a)

Output:
1.23

func (Decimal) Sign ¶

func (d Decimal) Sign() int

Sign returns:

-1 if d < 0
 0 if d == 0
+1 if d > 0

Example ¶

fmt.Println(MustParse("1.23").Sign())
fmt.Println(MustParse("-1.23").Sign())
fmt.Println(MustParse("0").Sign())

Output:
1
-1
0

func (Decimal) Sqrt ¶

func (d Decimal) Sqrt() (Decimal, error)

Sqrt returns the square root of d using Newton-Raphson method. The result will have at most defaultPrec digits after the decimal point. Returns error if d < 0

Examples:

Sqrt(4) = 2
Sqrt(2) = 1.4142135623730950488

Example ¶

fmt.Println(MustParse("1.21").Sqrt())
fmt.Println(MustParse("0").Sqrt())
fmt.Println(MustParse("-1.21").Sqrt())

Output:
1.1 <nil>
0 <nil>
0 can't calculate square root of negative number

func (Decimal) String ¶

func (d Decimal) String() string

String returns the string representation of the decimal. Trailing zeros will be removed.

Example ¶

fmt.Println(MustParse("1.23").String())
fmt.Println(MustParse("-1.230000").String())

Output:
1.23
-1.23

func (Decimal) StringFixed ¶

func (d Decimal) StringFixed(prec uint8) string

StringFixed returns the string representation of the decimal with fixed prec. Trailing zeros will not be removed.

Special case: if the decimal is zero, it will return "0" regardless of the prec.

Example ¶

fmt.Println(MustParse("1.23").StringFixed(4))
fmt.Println(MustParse("-1.230000").StringFixed(5))

Output:
1.2300
-1.23000

func (Decimal) Sub ¶

func (d Decimal) Sub(e Decimal) Decimal

Sub returns d - e

Example ¶

a := MustParse("1.23")
b := MustParse("4.12475")
c := a.Sub(b)
fmt.Println(c)

Output:
-2.89475

func (Decimal) Sub64 ¶

func (d Decimal) Sub64(e uint64) Decimal

Sub64 returns d - e where e is a uint64

Example ¶

a := MustParse("1.23")
c := a.Sub64(4)
fmt.Println(c)

Output:
-2.77

func (Decimal) Trunc ¶

func (d Decimal) Trunc(prec uint8) Decimal

Trunc returns d after truncating the decimal to the specified prec.

Examples:

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

Example ¶

fmt.Println(MustParse("1.23").Trunc(1))
fmt.Println(MustParse("-1.23").Trunc(5))

Output:
1.2
-1.23

func (*Decimal) UnmarshalBinary ¶

func (d *Decimal) UnmarshalBinary(data []byte) error

Example ¶

var a Decimal
_ = a.UnmarshalBinary([]byte{0, 2, 11, 0, 0, 0, 0, 0, 0, 0, 123})
fmt.Println(a)

Output:
1.23

func (*Decimal) UnmarshalJSON ¶

func (d *Decimal) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

Example ¶

var a Decimal
_ = a.UnmarshalJSON([]byte("1.23"))
fmt.Println(a)

Output:
1.23

func (*Decimal) UnmarshalText ¶ added in v1.2.0

func (d *Decimal) UnmarshalText(data []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

Example ¶

var a Decimal
_ = a.UnmarshalText([]byte("1.23"))
fmt.Println(a)

Output:
1.23

func (Decimal) Value ¶

func (d Decimal) Value() (driver.Value, error)

Value implements driver.Valuer interface.

Example ¶

fmt.Println(MustParse("1.2345").Value())

Output:
1.2345 <nil>

type NullDecimal ¶

type NullDecimal struct {
	Decimal Decimal
	Valid   bool
}

NullDecimal is a nullable Decimal.

func (*NullDecimal) Scan ¶

func (d *NullDecimal) Scan(src any) error

Scan implements sql.Scanner interface.

Example ¶

var a, b NullDecimal
_ = a.Scan("1.23")
_ = b.Scan(nil)

fmt.Println(a)
fmt.Println(b)

Output:
{1.23 true}
{0 false}

func (NullDecimal) Value ¶

func (d NullDecimal) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

Example ¶

fmt.Println(NullDecimal{Decimal: MustParse("1.2345"), Valid: true}.Value())
fmt.Println(NullDecimal{}.Value())

Output:
1.2345 <nil>
<nil> <nil>

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

udecimal

Installation

Features

Documentation

Usage

Why another decimal library?

Rounding Methods

Examples:

How it works

Credits

License

Documentation ¶

Overview ¶

Codec ¶

Index ¶

Examples ¶

Constants ¶

Variables ¶

Functions ¶

func SetDefaultPrecision ¶

Types ¶

type Decimal ¶

func MustFromFloat64 ¶

func MustFromInt64 ¶

func MustFromUint64 ¶

func MustParse ¶

func NewFromFloat64 ¶

func NewFromHiLo ¶

func NewFromInt64 ¶

func NewFromUint64 ¶

func Parse ¶

func (Decimal) Abs ¶

func (Decimal) Add ¶

func (Decimal) Add64 ¶

func (Decimal) Ceil ¶

func (Decimal) Cmp ¶

func (Decimal) Div ¶

func (Decimal) Div64 ¶

func (Decimal) Equal ¶ added in v1.2.0

func (Decimal) Floor ¶

func (Decimal) InexactFloat64 ¶

func (Decimal) IsNeg ¶

func (Decimal) IsPos ¶

func (Decimal) IsZero ¶

func (Decimal) MarshalBinary ¶

func (Decimal) MarshalJSON ¶

func (Decimal) MarshalText ¶ added in v1.2.0

func (Decimal) Mul ¶

func (Decimal) Mul64 ¶

func (Decimal) Neg ¶

func (Decimal) PowInt ¶

func (Decimal) Prec ¶

func (Decimal) RoundBank ¶

func (Decimal) RoundHAZ ¶

func (Decimal) RoundHTZ ¶

func (*Decimal) Scan ¶

func (Decimal) Sign ¶

func (Decimal) Sqrt ¶

func (Decimal) String ¶

func (Decimal) StringFixed ¶

func (Decimal) Sub ¶

func (Decimal) Sub64 ¶

func (Decimal) Trunc ¶

func (*Decimal) UnmarshalBinary ¶

func (*Decimal) UnmarshalJSON ¶

func (*Decimal) UnmarshalText ¶ added in v1.2.0

func (Decimal) Value ¶

type NullDecimal ¶

func (*NullDecimal) Scan ¶

func (NullDecimal) Value ¶

Source Files ¶