decimal

README

decimal

Exact, arbitrary-precision fixed-point decimal for Go. A value is coefficient × 10⁻ˢᶜᵃˡᵉ with a big.Int coefficient — no precision ceiling, no float, immutable.

Unlike int64/uint64 decimal & money libraries (which cap around 19 digits — about $9.20 at 18 decimals), this holds a fiat cent and an 18-decimal on-chain wei balance with equal exactness. 0.1 + 0.2 is exactly 0.3.

d := decimal.MustParse("6.60")
cost := decimal.New(200, 0).Mul(d).Quo(decimal.New(1_000_000, 0), 18) // 200 tokens @ $6.60/1M
cost.String() // "0.00132"  (never floored to 0)

The numeric core beneath hanzoai/money. Stdlib only. BSD-3-Clause.

Documentation

Overview

Package decimal is an exact, arbitrary-precision fixed-point decimal number.

A value is coefficient × 10^-scale, where the coefficient is a big.Int and the scale is a non-negative number of fractional digits. Because the coefficient is a big.Int there is NO precision ceiling — unlike int64/uint64 money types (which cap around 19 digits, ~$9.20 at 18 decimals), a Decimal holds a fiat cent and an 18-decimal on-chain wei balance with equal exactness. No float64 ever touches a value, so arithmetic is exact and reproducible; 0.1 + 0.2 is exactly 0.3.

A Decimal is IMMUTABLE: every operation returns a new value and the wrapped big.Int is never mutated after construction, so a Decimal is a safe value object to copy, compare and share. The zero value is a valid 0 (scale 0).

This is the numeric core beneath github.com/hanzoai/money — the ONE exact-number definition for the Hanzo stack. It is a leaf: stdlib only, no money/currency concern.

Index

• type Decimal
  • func MustParse(s string) Decimal
  • func New(coef int64, scale int32) Decimal
  • func NewFromBig(coef *big.Int, scale int32) Decimal
  • func Parse(s string) (Decimal, error)
  • func Zero() Decimal
  • func (d Decimal) Abs() Decimal
  • func (d Decimal) Add(b Decimal) Decimal
  • func (d Decimal) Cmp(b Decimal) int
  • func (d Decimal) Coef() *big.Int
  • func (d Decimal) Equal(b Decimal) bool
  • func (d Decimal) IsZero() bool
  • func (d Decimal) MarshalJSON() ([]byte, error)
  • func (d Decimal) Mul(b Decimal) Decimal
  • func (d Decimal) Neg() Decimal
  • func (d Decimal) Quo(b Decimal, scale int32) Decimal
  • func (d Decimal) Rescale(scale int32) Decimal
  • func (d Decimal) Round(scale int32) Decimal
  • func (d Decimal) Scale() int32
  • func (d Decimal) Sign() int
  • func (d Decimal) String() string
  • func (d Decimal) Sub(b Decimal) Decimal
  • func (d *Decimal) UnmarshalJSON(b []byte) error

Types

type Decimal

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

Decimal is an exact fixed-point number: Coef × 10^-Scale.

func MustParse

func MustParse(s string) Decimal

MustParse is Parse that panics on error — for constants/tests.

func New

func New(coef int64, scale int32) Decimal

New returns coef × 10^-scale. A negative scale is clamped to 0 (scale is fractional digits; a "negative scale" is folded into the coefficient).

func NewFromBig

func NewFromBig(coef *big.Int, scale int32) Decimal

NewFromBig returns coef × 10^-scale, copying coef. Negative scale multiplies the coefficient up so the stored scale stays >= 0.

func Parse

func Parse(s string) (Decimal, error)

Parse reads a decimal string ("123", "-0.00132", "+6.60") EXACTLY — no float. The scale is the number of fractional digits written (so "6.60" has scale 2). An empty string is 0.

func Zero

func Zero() Decimal

Zero is the additive identity (0 at scale 0).

func (Decimal) Abs

func (d Decimal) Abs() Decimal

Abs returns |d|.

func (Decimal) Add

func (d Decimal) Add(b Decimal) Decimal

Add returns d + b, at the finer of the two scales (exact).

func (Decimal) Cmp

func (d Decimal) Cmp(b Decimal) int

Cmp reports −1, 0, +1 as d <, ==, > b (scale-aligned).

func (Decimal) Coef

func (d Decimal) Coef() *big.Int

Coef returns a fresh big.Int of the coefficient (the value is Coef × 10^-Scale).

func (Decimal) Equal

func (d Decimal) Equal(b Decimal) bool

Equal reports whether d and b are numerically equal (scale-independent).

func (Decimal) IsZero

func (d Decimal) IsZero() bool

IsZero reports whether d == 0.

func (Decimal) MarshalJSON

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

MarshalJSON emits the exact decimal string — a STRING, never a JSON number.

func (Decimal) Mul

func (d Decimal) Mul(b Decimal) Decimal

Mul returns d × b EXACTLY; the result scale is the sum of the operand scales.

func (Decimal) Neg

func (d Decimal) Neg() Decimal

Neg returns −d.

func (Decimal) Quo

func (d Decimal) Quo(b Decimal, scale int32) Decimal

Quo returns d ÷ b rounded to `scale` fractional digits (half-away-from-zero). Panics on divide-by-zero (a programming error, like integer division).

func (Decimal) Rescale

func (d Decimal) Rescale(scale int32) Decimal

Rescale returns the value at exactly `scale` fractional digits. Increasing the scale is exact; decreasing rounds half-away-from-zero (banker's rounding is not used — money convention is half-up on magnitude).

func (Decimal) Round

func (d Decimal) Round(scale int32) Decimal

Round rounds to `scale` fractional digits (alias of Rescale for reducing scale; pads when increasing).

func (Decimal) Scale

func (d Decimal) Scale() int32

Scale reports the number of fractional digits.

func (Decimal) Sign

func (d Decimal) Sign() int

Sign reports −1, 0, +1 as d <, ==, > 0.

func (Decimal) String

func (d Decimal) String() string

String renders the exact decimal ("6.6", "0.00132", "-0.5", "0"). Trailing fractional zeros implied by the scale are kept only up to the scale, then trimmed.

func (Decimal) Sub

func (d Decimal) Sub(b Decimal) Decimal

Sub returns d − b, at the finer of the two scales (exact).

func (*Decimal) UnmarshalJSON

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

UnmarshalJSON accepts a quoted decimal string or a bare number, parsed exactly.