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 (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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Decimal ¶
type Decimal struct {
// contains filtered or unexported fields
}
Decimal is an exact fixed-point number: Coef × 10^-Scale.
func New ¶
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 ¶
NewFromBig returns coef × 10^-scale, copying coef. Negative scale multiplies the coefficient up so the stored scale stays >= 0.
func Parse ¶
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.
The grammar is exactly [+|-] digits [. digits] with at least one digit, and it is enforced by checking the digits rather than by asking big.Int to. Delegating the check let malformed input through in the worst possible way: this function strips ONE leading sign, and big.Int.SetString then accepted a SECOND one, so "--5" parsed as +5 — a sign inversion on a value that is usually money, where a credit silently becomes a charge. A bare "-", "+" or "." fell through the other side of the same gap, taking the intPart=="" → "0" fallback and parsing as a confident zero. Both now return an error.
func (Decimal) Coef ¶
Coef returns a fresh big.Int of the coefficient (the value is Coef × 10^-Scale).
func (Decimal) MarshalJSON ¶
MarshalJSON emits the exact decimal string — a STRING, never a JSON number.
func (Decimal) Quo ¶
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 ¶
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 ¶
Round rounds to `scale` fractional digits (alias of Rescale for reducing scale; pads when increasing).
func (Decimal) 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) UnmarshalJSON ¶
UnmarshalJSON accepts a quoted decimal string or a bare number, parsed exactly.
Source Files