Documentation
¶
Overview ¶
Package moneyx — ISO 4217 currency precision lookup and strict conversion helpers. The conversions in moneyx.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 moneyx provides conversions between common.v1.Money protobuf messages and decimalx.Decimal values.
moneyx is the successor to the deprecated package money. It targets common.v1.Money (from buf.build/antinvestor/common) so services can standardize on a single Money type across protos, Go, and Dart without per-call-site converters between google.type.Money and the shared antinvestor type.
Index ¶
- Constants
- Variables
- func CompareMoney(a, b *commonv1.Money) int
- func Decimals(currencyCode string) int32
- func FromFloat64(currency string, amount float64) *commonv1.Money
- func FromInt64(currency string, amount int64, decimals int32) *commonv1.Money
- func FromMinorUnitsByCurrency(currency string, minor int64) *commonv1.Money
- func FromMoney(m *commonv1.Money) decimalx.Decimal
- func FromSmallestUnit(currency string, amount int64, decimals int32) *commonv1.Money
- func FromSmallestUnitDecimal(currency string, amount decimalx.Decimal, decimals int32) *commonv1.Money
- func ToCents(units int64, nanos int32) int64
- func ToFloat64(m *commonv1.Money) float64
- func ToInt64(m *commonv1.Money, decimals int32) int64
- func ToMinorUnitsByCurrency(m *commonv1.Money, expectedCurrency string) (int64, error)
- func ToMoney(currency string, amount decimalx.Decimal) *commonv1.Money
- func ToSmallestUnit(m *commonv1.Money, decimals int32) int64
- func ToSmallestUnitDecimal(m *commonv1.Money, decimals int32) decimalx.Decimal
- func ToSmallestUnitStrict(m *commonv1.Money, expectedCurrency string, decimals int32) (int64, error)
Constants ¶
const ( // DecimalsZero is used by codes like JPY, KRW, UGX where the major and // minor unit are identical. DecimalsZero int32 = 0 // DecimalsTwo is the default precision and covers the majority of ISO // 4217 codes. DecimalsTwo int32 = 2 // DecimalsThree is used by Gulf and Tunisian codes (BHD, IQD, etc.). DecimalsThree int32 = 3 )
Default ISO 4217 fractional digit counts.
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 *commonv1.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 *commonv1.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 *commonv1.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 ¶
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 common.v1.Money.
func FromInt64 ¶
FromInt64 converts an int64 amount in the smallest unit to a common.v1.Money. Shorthand for FromSmallestUnit.
func FromMinorUnitsByCurrency ¶
FromMinorUnitsByCurrency converts an int64 minor-unit amount and a currency code to a *commonv1.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 common.v1.Money. For example, 1500000000000000000 wei with decimals=18 and currency "ETH" returns Money{Units: 1, Nanos: 500000000}.
func FromSmallestUnitDecimal ¶
func FromSmallestUnitDecimal( currency string, amount decimalx.Decimal, decimals int32, ) *commonv1.Money
FromSmallestUnitDecimal converts a Decimal in the smallest unit back to a common.v1.Money. Use this when the smallest-unit value may exceed int64 range.
func ToInt64 ¶
ToInt64 converts a common.v1.Money to an int64 in the smallest unit. Shorthand for ToSmallestUnit.
func ToMinorUnitsByCurrency ¶
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 common.v1.Money protobuf message. Units holds the integer part; Nanos holds the fractional part scaled to 10^9.
func ToSmallestUnit ¶
ToSmallestUnit converts a common.v1.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 common.v1.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 ¶
func ToSmallestUnitStrict( m *commonv1.Money, expectedCurrency string, decimals int32, ) (int64, error)
ToSmallestUnitStrict converts a *commonv1.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