Documentation
¶
Overview ¶
Package money — ISO 4217 currency precision lookup and strict conversion helpers. The conversions in money.go take an explicit `decimals` parameter; in many callers the decimals are determined solely by the currency code, and a strict check that the wire money matches an expected currency avoids silent currency coercion bugs.
Package money provides conversions between google.type.Money protobuf messages and decimalx.Decimal values.
Index ¶
- Constants
- Variables
- func CompareMoney(a, b *money.Money) int
- func Decimals(currencyCode string) int32
- func FromFloat64(currency string, amount float64) *money.Money
- func FromInt64(currency string, amount int64, decimals int32) *money.Money
- func FromMinorUnitsByCurrency(currency string, minor int64) *money.Money
- func FromMoney(m *money.Money) decimalx.Decimal
- func FromSmallestUnit(currency string, amount int64, decimals int32) *money.Money
- func FromSmallestUnitDecimal(currency string, amount decimalx.Decimal, decimals int32) *money.Money
- func ToCents(units int64, nanos int32) int64
- func ToFloat64(m *money.Money) float64
- func ToInt64(m *money.Money, decimals int32) int64
- func ToMinorUnitsByCurrency(m *money.Money, expectedCurrency string) (int64, error)
- func ToMoney(currency string, amount decimalx.Decimal) *money.Money
- func ToSmallestUnit(m *money.Money, decimals int32) int64
- func ToSmallestUnitDecimal(m *money.Money, decimals int32) decimalx.Decimal
- func ToSmallestUnitStrict(m *money.Money, expectedCurrency string, decimals int32) (int64, error)
Constants ¶
const CentsPerUnit = 100
CentsPerUnit is the number of cents in one currency unit.
const NanosPerCent = 10_000_000
NanosPerCent is the number of nanos in one cent.
Variables ¶
var ErrCurrencyMismatch = errors.New("money: currency mismatch")
ErrCurrencyMismatch is returned when a *money.Money's currency code does not match the expected currency. Callers should never silently coerce money between currencies; converting an off-currency amount without explicit FX is a correctness bug.
var ErrNilMoney = errors.New("money: nil input")
ErrNilMoney is returned when a nil *money.Money is passed to a strict converter that requires a non-nil input.
var ErrSignMismatch = errors.New("money: units and nanos have opposite signs")
ErrSignMismatch is returned when a *money.Money has units and nanos with opposite signs, which is invalid per google.type.Money semantics.
Functions ¶
func CompareMoney ¶
CompareMoney compares two Money values numerically, returning -1, 0, or 1.
func Decimals ¶ added in v0.8.0
Decimals returns the ISO 4217 minor-unit count (0, 2, or 3) for the supplied currency code. The lookup is case-insensitive. Unknown or empty codes default to 2 — the most common precision and the safest fallback for codes outside the published list.
func FromFloat64 ¶
FromFloat64 converts a float64 amount and currency code into a google.type.Money.
func FromInt64 ¶
FromInt64 converts an int64 amount in the smallest unit to a google.type.Money. Shorthand for FromSmallestUnit.
func FromMinorUnitsByCurrency ¶ added in v0.8.0
FromMinorUnitsByCurrency converts an int64 minor-unit amount and a currency code to a *money.Money, looking up the ISO 4217 precision for the code. The returned message has the supplied currency stamped on it; if the currency is unknown the conversion uses 2 decimals (the Decimals fallback).
func FromSmallestUnit ¶
FromSmallestUnit converts a smallest-unit integer back to a google.type.Money. For example, 1500000000000000000 wei with decimals=18 and currency "ETH" returns Money{Units: 1, Nanos: 500000000}.
func FromSmallestUnitDecimal ¶
FromSmallestUnitDecimal converts a Decimal in the smallest unit back to a google.type.Money. Use this when the smallest-unit value may exceed int64 range.
func ToInt64 ¶
ToInt64 converts a google.type.Money to an int64 in the smallest unit. Shorthand for ToSmallestUnit.
func ToMinorUnitsByCurrency ¶ added in v0.8.0
ToMinorUnitsByCurrency is a shortcut combining Decimals + ToSmallestUnitStrict: it looks up the ISO 4217 precision for expectedCurrency, validates currency match, and converts. Use it when the caller wants currency-aware precision without juggling the decimals argument.
func ToMoney ¶
ToMoney converts a Decimal to a google.type.Money protobuf message. Units holds the integer part; Nanos holds the fractional part scaled to 10^9.
func ToSmallestUnit ¶
ToSmallestUnit converts a google.type.Money to its smallest unit representation given the number of decimal places for the currency. For example, 1.5 ETH with decimals=18 returns 1500000000000000000 (wei).
func ToSmallestUnitDecimal ¶
ToSmallestUnitDecimal converts a google.type.Money to a Decimal representing the amount in the smallest unit. This avoids int64 overflow for very large values (e.g. wei amounts exceeding MaxInt64).
func ToSmallestUnitStrict ¶ added in v0.8.0
ToSmallestUnitStrict converts a *money.Money to int64 minor units, validating that the currency matches expectedCurrency (case-insensitive) and that the units/nanos signs agree. It is the strict variant of ToSmallestUnit for callers that need to refuse silent coercion.
Types ¶
This section is empty.
Source Files