Documentation
¶
Overview ¶
Package decimal is forge's fixed-point decimal type for money and crypto.
It wraps alpacahq/alpacadecimal (a shopspring/decimal drop-in that keeps the common case in a single int64 and falls back to big.Int only when a value exceeds that envelope) behind a stable forge API, so the backend can change without touching callers. Arithmetic is exact — never float64.
Money adds asset + smallest-unit scale and a sum-conserving Allocate/Split, so distributing a total across parts never creates or loses a minor unit.
Crypto note: the fast int64 path covers ~12 dp and |value| ≲ 9.22M; 8-dp (sat) and 18-dp (wei) values beyond that stay correct via the big.Int fallback. For hot-path crypto balances, prefer integer minor units at the asset's scale (Money carries that scale) and widen to Decimal only for cross-asset or display math.
Index ¶
- Variables
- type Decimal
- func (d Decimal) Abs() Decimal
- func (d Decimal) Add(o Decimal) Decimal
- func (d Decimal) BigInt() *big.Int
- func (d Decimal) Cmp(o Decimal) int
- func (d Decimal) Div(o Decimal) Decimal
- func (d Decimal) DivRound(o Decimal, precision int32) Decimal
- func (d Decimal) Equal(o Decimal) bool
- func (d Decimal) Exponent() int32
- func (d Decimal) GreaterThan(o Decimal) bool
- func (d Decimal) GreaterThanOrEqual(o Decimal) bool
- func (d Decimal) InexactFloat64() float64
- func (d Decimal) IntPart() int64
- func (d Decimal) IsNegative() bool
- func (d Decimal) IsPositive() bool
- func (d Decimal) IsZero() bool
- func (d Decimal) LessThan(o Decimal) bool
- func (d Decimal) LessThanOrEqual(o Decimal) bool
- func (d Decimal) MarshalJSON() ([]byte, error)
- func (d Decimal) Mod(o Decimal) Decimal
- func (d Decimal) Mul(o Decimal) Decimal
- func (d Decimal) Neg() Decimal
- func (d Decimal) Round(places int32) Decimal
- func (d Decimal) RoundBank(places int32) Decimal
- func (d Decimal) RoundDown(places int32) Decimal
- func (d *Decimal) Scan(v any) error
- func (d Decimal) Shift(shift int32) Decimal
- func (d Decimal) Sign() int
- func (d Decimal) String() string
- func (d Decimal) StringFixed(places int32) string
- func (d Decimal) Sub(o Decimal) Decimal
- func (d *Decimal) UnmarshalJSON(b []byte) error
- func (d Decimal) Value() (driver.Value, error)
- type Money
- func (m Money) Add(o Money) (Money, error)
- func (m Money) Allocate(ratios ...int) ([]Money, error)
- func (m Money) Amount() Decimal
- func (m Money) Asset() string
- func (m Money) IsZero() bool
- func (m Money) Scale() int32
- func (m Money) Split(n int) ([]Money, error)
- func (m Money) String() string
- func (m Money) Sub(o Money) (Money, error)
Constants ¶
This section is empty.
Variables ¶
var ( ErrAssetMismatch = errors.New("decimal: money asset mismatch") ErrBadRatios = errors.New("decimal: ratios must be non-empty and sum positive") ErrBadSplit = errors.New("decimal: split count must be positive") )
var Zero = Decimal{}
Zero is the additive identity.
Functions ¶
This section is empty.
Types ¶
type Decimal ¶
type Decimal struct {
// contains filtered or unexported fields
}
Decimal is an exact fixed-point number.
func FromString ¶
FromString parses a decimal string (e.g. "12.34", "-0.000000000000000001").
func NewFromBigInt ¶
NewFromBigInt builds value × 10^exp from an arbitrary-precision coefficient.
func RequireFromString ¶
RequireFromString parses s and panics on error — for constants/tests only.
func (Decimal) GreaterThan ¶
func (Decimal) GreaterThanOrEqual ¶
func (Decimal) InexactFloat64 ¶
InexactFloat64 returns the nearest float64 — lossy; for display/metrics only, never for money arithmetic.
func (Decimal) IsNegative ¶
func (Decimal) IsPositive ¶
func (Decimal) LessThanOrEqual ¶
func (Decimal) MarshalJSON ¶
MarshalJSON always emits a quoted string (never a float) so a JSON consumer can't silently lose precision parsing the value as a number.
func (Decimal) StringFixed ¶
func (*Decimal) UnmarshalJSON ¶
UnmarshalJSON accepts a quoted string or a bare number; "" / null decode to zero.
type Money ¶
type Money struct {
// contains filtered or unexported fields
}
Money is an Amount in an asset, rounded to the asset's smallest unit (scale: 2 for USD, 8 for BTC/sat, 18 for ETH/wei).
func (Money) Allocate ¶
Allocate splits the amount across the given integer ratios, conserving the sum exactly — no minor unit created or lost. Any indivisible remainder is handed out one unit at a time to the first parts (round-robin).
Source Files