Add negation, abs, min/max, and checked sum for Money #43

Closed
opened 2026-08-17 13:37:35 +00:00 by rosa · 1 comment
Owner

Problem

Common single-value operations are missing, so callers drop down to Decimal and rebuild the Money:

  • negation and absolute value
  • min / max between two amounts of the same currency
  • summing an iterator of Money

Proposal

  • checked_neg() -> Option<Money> and checked_abs() -> Option<Money> (Decimal negation can overflow at the extremes).
  • checked_min(other) -> Result<Money, MoneyError> and checked_max(other) -> Result<Money, MoneyError>, erroring when the currencies differ, matching checked_add.
  • A checked sum over IntoIterator<Item = Money>, erroring when the currencies differ or the total is too large for a Decimal. The std Sum trait cannot return Result, 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.

## Problem Common single-value operations are missing, so callers drop down to `Decimal` and rebuild the `Money`: - negation and absolute value - `min` / `max` between two amounts of the same currency - summing an iterator of `Money` ## Proposal - `checked_neg() -> Option<Money>` and `checked_abs() -> Option<Money>` (`Decimal` negation can overflow at the extremes). - `checked_min(other) -> Result<Money, MoneyError>` and `checked_max(other) -> Result<Money, MoneyError>`, erroring when the currencies differ, matching `checked_add`. - A checked sum over `IntoIterator<Item = Money>`, erroring when the currencies differ or the total is too large for a `Decimal`. The std `Sum` trait cannot return `Result`, 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.
Author
Owner

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add abs, checked_min/checked_max, and a checked sum (method and Sum impls) for Money

Correction to the issue body: negation is already covered and cannot fail. Money implements Neg (for values and references), and rust_decimal::Decimal stores its sign as a flag, so negating flips the flag and never overflows — -Decimal::MAX == Decimal::MIN. Do not add checked_neg. For the same reason abs is infallible and must not be a checked_ method.

Current behavior:

  • Money has Neg, PartialOrd (returns None when the currencies differ), and the four checked arithmetic methods (checked_add, checked_sub, checked_mul, checked_div) returning Result<Money, MoneyError>.
  • Summing an iterator of Money has two panicking paths: Sum<Money> for Option<Money> (panics when the currencies differ or the total overflows) and Sum<Money> for MoneyBag (keeps mixed currencies apart). There is no error-returning sum.
  • There is no abs, min, or max.

Desired behavior:

  • Money::abs(self) -> Money — same currency, non-negative amount. Infallible.
  • Money::checked_min(self, other: Money) -> Result<Money, MoneyError> and Money::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 of checked_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 a Decimal. Stops at the first error.
  • impl Sum<Money> for Result<Option<Money>, MoneyError> — the trait-shaped twin of checked_sum for use at the end of iterator chains. Ok(None) for an empty iterator; otherwise Ok(Some(total)), Err(MoneyError::CurrencyMismatch), or Err(MoneyError::Overflow).
  • Mirror the reference variants the existing impls have: wherever a new trait impl consumes Money, add the &'a Money twin (as Sum<&'a Money> for Option<Money> does today).

Key interfaces:

  • Money — gains abs, checked_min, checked_max, checked_sum; no changes to existing methods.
  • MoneyError — no new variants needed; reuse CurrencyMismatch and Overflow.
  • Doc comments carry executable doctests as examples, and every fallible item's Errors/Panics note follows the same template as the existing checked_ methods. The docs on the existing Sum impls should point readers at the checked alternatives (replacing the current "fold with checked_add" advice).

Acceptance criteria:

  • Money::abs returns the positive counterpart of a negative amount and leaves a positive amount unchanged, in the same currency.
  • checked_min/checked_max return the expected operand for same-currency pairs and Err(MoneyError::CurrencyMismatch) for mixed pairs.
  • Money::checked_sum over same-currency amounts returns the total; over an empty iterator returns zero in the given currency; over mixed currencies returns Err(MoneyError::CurrencyMismatch).
  • iter.sum::<Result<Option<Money>, MoneyError>>() returns Ok(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.
  • Overflow paths are exercised in tests using amounts near Decimal::MAX.
  • The fmtcheck, ci, and clippy mise tasks pass.

Out of scope:

  • checked_neg (negation cannot fail; Neg already exists).
  • A total order (Ord) for Money, or panicking min/max.
  • Any change to MoneyBag's sums or to the panicking Sum<Money> for Option<Money> behavior.
  • Rounding, allocation, or currency conversion.
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Add `abs`, `checked_min`/`checked_max`, and a checked sum (method and `Sum` impls) for `Money` **Correction to the issue body:** negation is already covered and cannot fail. `Money` implements `Neg` (for values and references), and `rust_decimal::Decimal` stores its sign as a flag, so negating flips the flag and never overflows — `-Decimal::MAX == Decimal::MIN`. Do not add `checked_neg`. For the same reason `abs` is infallible and must not be a `checked_` method. **Current behavior:** - `Money` has `Neg`, `PartialOrd` (returns `None` when the currencies differ), and the four checked arithmetic methods (`checked_add`, `checked_sub`, `checked_mul`, `checked_div`) returning `Result<Money, MoneyError>`. - Summing an iterator of `Money` has two panicking paths: `Sum<Money> for Option<Money>` (panics when the currencies differ or the total overflows) and `Sum<Money> for MoneyBag` (keeps mixed currencies apart). There is no error-returning sum. - There is no `abs`, `min`, or `max`. **Desired behavior:** - `Money::abs(self) -> Money` — same currency, non-negative amount. Infallible. - `Money::checked_min(self, other: Money) -> Result<Money, MoneyError>` and `Money::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 of `checked_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 a `Decimal`. Stops at the first error. - `impl Sum<Money> for Result<Option<Money>, MoneyError>` — the trait-shaped twin of `checked_sum` for use at the end of iterator chains. `Ok(None)` for an empty iterator; otherwise `Ok(Some(total))`, `Err(MoneyError::CurrencyMismatch)`, or `Err(MoneyError::Overflow)`. - Mirror the reference variants the existing impls have: wherever a new trait impl consumes `Money`, add the `&'a Money` twin (as `Sum<&'a Money> for Option<Money>` does today). **Key interfaces:** - `Money` — gains `abs`, `checked_min`, `checked_max`, `checked_sum`; no changes to existing methods. - `MoneyError` — no new variants needed; reuse `CurrencyMismatch` and `Overflow`. - Doc comments carry executable doctests as examples, and every fallible item's `Errors`/`Panics` note follows the same template as the existing `checked_` methods. The docs on the existing `Sum` impls should point readers at the checked alternatives (replacing the current "fold with `checked_add`" advice). **Acceptance criteria:** - [ ] `Money::abs` returns the positive counterpart of a negative amount and leaves a positive amount unchanged, in the same currency. - [ ] `checked_min`/`checked_max` return the expected operand for same-currency pairs and `Err(MoneyError::CurrencyMismatch)` for mixed pairs. - [ ] `Money::checked_sum` over same-currency amounts returns the total; over an empty iterator returns zero in the given currency; over mixed currencies returns `Err(MoneyError::CurrencyMismatch)`. - [ ] `iter.sum::<Result<Option<Money>, MoneyError>>()` returns `Ok(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. - [ ] Overflow paths are exercised in tests using amounts near `Decimal::MAX`. - [ ] The `fmtcheck`, `ci`, and `clippy` mise tasks pass. **Out of scope:** - `checked_neg` (negation cannot fail; `Neg` already exists). - A total order (`Ord`) for `Money`, or panicking `min`/`max`. - Any change to `MoneyBag`'s sums or to the panicking `Sum<Money> for Option<Money>` behavior. - Rounding, allocation, or currency conversion.
rosa closed this issue 2026-08-17 14:46:18 +00:00
Sign in to join this conversation.
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
rosa/lucre#43
No description provided.