govalues/decimal

The decimal package implements the necessary interfaces for direct compatibility with common Go data handling packages:

• mongo-driver/bson (BSON)
• encoding/json (JSON)
• encoding/xml (XML)
• database/sql (SQL)

To add the decimal package to your Go workspace, use the following command:

go get github.com/govalues/decimal

The decimal type supports standard Go formatting verbs, allowing you to control precision and notation in fmt functions.

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

You can round, ceil, floor, or truncate decimal values to a specific number of decimal places. The package uses half-to-even (banker's rounding) for all rounding operations.

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

Decimals can be converted back to standard Go types like int64, float64, or their string representation.

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

You can create decimal values using several constructor methods. Note that most constructors return both the value and an error, which should be handled to ensure safety (e.g., in case of parsing errors).

// d = 8
d, _ := decimal.New(8, 0)

// e = 12.5
e, _ := decimal.Parse("12.5")

// f = 2.567
f, _ := decimal.NewFromFloat64(2.567)

// g = 7.896
g, _ := decimal.NewFromInt64(7, 896, 3)

The SubQuo and SubQuoExact methods compute the fused operation d - e / f using at least double precision during intermediate rounding.

• SubQuo(e, f Decimal) (Decimal, error): Computes d - e / f with default rounding.
• SubQuoExact(e, f Decimal, scale int) (Decimal, error): Computes d - e / f and requires that no significant digits are lost during rounding at the specified scale.

Errors are returned if:

• The divisor f is 0.
• The integer part of the result exceeds MaxPrec digits.
• In SubQuoExact, the provided scale is outside the allowed MinScale to MaxScale range, or significant digits are lost during rounding.

// Example usage (conceptual)
// result = d - (e / f)
result, err := d.SubQuo(e, f)

// result = d - (e / f) with specific scale
result, err = d.SubQuoExact(e, f, 2)

Compute exponential functions:

• Exp() (Decimal, error): Returns the (possibly rounded) exponential $e^d$.
• Expm1() (Decimal, error): Returns the shifted exponential $e^d - 1$.

Errors:

• Both return an error if the integer part of the result exceeds MaxPrec digits.

Use NewFromFloat64(f) to create a Decimal from a float64. This method returns an error if the float is NaN or Inf.

Use Float64() to convert a Decimal back to a float64. This uses banker's rounding (rounding half to even). Note that this conversion may lose precision because float64 has less precision than the Decimal type.

d, err := decimal.NewFromFloat64(3.14159)
f, ok := d.Float64()

The Clamp(min, max Decimal) (Decimal, error) method constrains a decimal within the provided [min, max] range.

• If d < min, it returns min.
• If d > max, it returns max.
• Otherwise, it returns d.

Errors are returned if min is numerically greater than max.

clamped, err := d.Clamp(min, max)

The fint type provides several methods to manipulate values as if they were decimal numbers by shifting the decimal point (scaling by powers of 10):

• lsh(shift int): Left shift. Calculates $x \times 10^{shift}$. Returns ok=false on overflow.
• rshHalfEven(shift int): Right shift with half-to-even rounding (banker's rounding). Calculates $round(x / 10^{shift})$.
• rshUp(shift int): Right shift with rounding away from zero. Calculates $\lceil x / 10^{shift} \rceil$.
• rshDown(shift int): Right shift with rounding towards zero. Calculates $\lfloor x / 10^{shift} \rfloor$.
• fsa(shift int, b byte): Fused Shift and Addition. Calculates $(x \times 10^{shift}) + b$. Useful for parsing digits.

x := fint(12345)

// Rounding examples
// rshHalfEven(2) -> 123
// rshUp(2)       -> 124
// rshDown(2)     -> 123