Add negation, abs, min/max, and checked sum for Money #43
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#43
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
Common single-value operations are missing, so callers drop down to
Decimaland rebuild theMoney:min/maxbetween two amounts of the same currencyMoneyProposal
checked_neg() -> Option<Money>andchecked_abs() -> Option<Money>(Decimalnegation can overflow at the extremes).checked_min(other) -> Result<Money, MoneyError>andchecked_max(other) -> Result<Money, MoneyError>, erroring when the currencies differ, matchingchecked_add.IntoIterator<Item = Money>, erroring when the currencies differ or the total is too large for aDecimal. The stdSumtrait cannot returnResult, so this is a free function or an extension method; an empty iterator has no currency, so it likely takes the expected currency as an argument.Each item is small; the sum's signature is the only design question.
Agent Brief
Category: enhancement
Summary: Add
abs,checked_min/checked_max, and a checked sum (method andSumimpls) forMoneyCorrection to the issue body: negation is already covered and cannot fail.
MoneyimplementsNeg(for values and references), andrust_decimal::Decimalstores its sign as a flag, so negating flips the flag and never overflows —-Decimal::MAX == Decimal::MIN. Do not addchecked_neg. For the same reasonabsis infallible and must not be achecked_method.Current behavior:
MoneyhasNeg,PartialOrd(returnsNonewhen the currencies differ), and the four checked arithmetic methods (checked_add,checked_sub,checked_mul,checked_div) returningResult<Money, MoneyError>.Moneyhas two panicking paths:Sum<Money> for Option<Money>(panics when the currencies differ or the total overflows) andSum<Money> for MoneyBag(keeps mixed currencies apart). There is no error-returning sum.abs,min, ormax.Desired behavior:
Money::abs(self) -> Money— same currency, non-negative amount. Infallible.Money::checked_min(self, other: Money) -> Result<Money, MoneyError>andMoney::checked_max(self, other: Money) -> Result<Money, MoneyError>— the smaller/larger of two amounts in the same currency;Err(MoneyError::CurrencyMismatch)when the currencies differ. Follow the wording and doc structure ofchecked_add.Money::checked_sum<I: IntoIterator<Item = Money>>(iter: I, currency: Currency) -> Result<Money, MoneyError>— the total of the amounts, all in the given currency. An empty iterator gives zero in that currency.Err(MoneyError::CurrencyMismatch)if any item's currency differs from the given one;Err(MoneyError::Overflow)if the total is too large for aDecimal. Stops at the first error.impl Sum<Money> for Result<Option<Money>, MoneyError>— the trait-shaped twin ofchecked_sumfor use at the end of iterator chains.Ok(None)for an empty iterator; otherwiseOk(Some(total)),Err(MoneyError::CurrencyMismatch), orErr(MoneyError::Overflow).Money, add the&'a Moneytwin (asSum<&'a Money> for Option<Money>does today).Key interfaces:
Money— gainsabs,checked_min,checked_max,checked_sum; no changes to existing methods.MoneyError— no new variants needed; reuseCurrencyMismatchandOverflow.Errors/Panicsnote follows the same template as the existingchecked_methods. The docs on the existingSumimpls should point readers at the checked alternatives (replacing the current "fold withchecked_add" advice).Acceptance criteria:
Money::absreturns the positive counterpart of a negative amount and leaves a positive amount unchanged, in the same currency.checked_min/checked_maxreturn the expected operand for same-currency pairs andErr(MoneyError::CurrencyMismatch)for mixed pairs.Money::checked_sumover same-currency amounts returns the total; over an empty iterator returns zero in the given currency; over mixed currencies returnsErr(MoneyError::CurrencyMismatch).iter.sum::<Result<Option<Money>, MoneyError>>()returnsOk(None)when empty,Ok(Some(total))for same-currency amounts, and the matching error for mixed currencies or overflow, for both owned and borrowed items.Decimal::MAX.fmtcheck,ci, andclippymise tasks pass.Out of scope:
checked_neg(negation cannot fail;Negalready exists).Ord) forMoney, or panickingmin/max.MoneyBag's sums or to the panickingSum<Money> for Option<Money>behavior.