Cash increment rounding and minor-unit accessor #42
Labels
No labels
kind
bug
kind
enhancement
kind
refactor
workflow
needs-info
workflow
needs-triage
workflow
ready-for-agent
workflow
ready-for-human
workflow
wontfix
No milestone
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
rosa/lucre#42
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Problem
Two gaps around minor units:
Money::roundrounds to a digit count, but cash transactions in some currencies round to an increment instead. Swiss francs and Danish kroner round cash to the nearest 0.05.Money::from_minorbuilds a value from minor units, but there is no accessor back out. Payment APIs such as Stripe take amounts as integer minor units, so callers currently reimplement the conversion by hand fromamount()andminor_digits().Proposal
round_to_increment(increment: Decimal, strategy: RoundingMode) -> Money(name open): round the amount to the nearest multiple of the increment.to_minor(&self) -> Result<i64, _>(name open): the amount in minor units. Errors if the amount has more precision than the currency's minor digits (the caller must round first) or overflows ani64.Open questions
to_minorshould round implicitly or error on sub-minor precision. Erroring keeps rounding policy explicit and in one place.Agent Brief
Category: enhancement
Summary: Add
Money::round_to_incrementandMoney::to_minorCurrent behavior:
Money::roundrounds to a digit count only; there is no way to round to acash increment such as 0.05 for Swiss francs.
Money::from_minorbuilds anamount from integer minor units, but there is no accessor back out — callers
that hand amounts to payment APIs (Stripe and similar) rebuild the conversion
by hand from
amount()andCurrency::minor_digits().Desired behavior:
round_to_increment(self, increment: Decimal, strategy: RoundingMode) -> Result<Money, MoneyError>increment, breaking ties bystrategy. Example: 3.33 CHF at increment 0.05 withHalfUpgives 3.35 CHF.1gives3,increment
1.00gives3.00.MoneyError::NonPositiveIncrement(new variant) if the increment iszero or negative. Diagnostic help: "use an increment above zero".
MoneyError::Overflowif an intermediate value is too large for aDecimal(a large amount divided by a tiny increment).to_minor(self, strategy: RoundingMode) -> Result<i64, MoneyError>from_minor:4.75 USD gives 475, 0.475 BHD gives 475.
strategyfirst, so sub-minorprecision never errors: 1.005 USD with
HalfUpgives 101.MoneyError::MinorUnitsOverflow(new variant) if the result is toolarge for an
i64. Message: "the amount in minor units is too large for ani64". Diagnostic help states thei64bound.Both new
MoneyErrorvariants follow the existing pattern:thiserrormessage,
miettediagnostic code underlucre::money::, and ahelpnote.Key interfaces:
Money— the two new methods above; no changes to existing methods.MoneyError— two new variants:NonPositiveIncrement,MinorUnitsOverflow.RoundingMode— used as-is; no new variants.Acceptance criteria:
Money::from_decimal("3.33".parse()?, Currency::CHF).round_to_increment("0.05".parse()?, RoundingMode::HalfUp)?equals 3.35 CHF1yields3, increment1.00yields3.00MoneyError::NonPositiveIncrementMoney::from_minor(n, c).to_minor(strategy)returnsOk(n)for any strategy; an amount whose minor units exceedi64::MAXreturnsMoneyError::MinorUnitsOverflowfmtcheck,ci, andclippymise tasks passOut of scope:
RoundingMode— separate issue if wantedfrom_minor,round, or formattingi64