Cash increment rounding and minor-unit accessor #42

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

Problem

Two gaps around minor units:

  1. Money::round rounds 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.
  2. Money::from_minor builds 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 from amount() and minor_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 an i64.

Open questions

  • Whether to_minor should round implicitly or error on sub-minor precision. Erroring keeps rounding policy explicit and in one place.
## Problem Two gaps around minor units: 1. `Money::round` rounds 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. 2. `Money::from_minor` builds 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 from `amount()` and `minor_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 an `i64`. ## Open questions - Whether `to_minor` should round implicitly or error on sub-minor precision. Erroring keeps rounding policy explicit and in one place.
Author
Owner

Agent Brief

Category: enhancement
Summary: Add Money::round_to_increment and Money::to_minor

Current behavior:
Money::round rounds to a digit count only; there is no way to round to a
cash increment such as 0.05 for Swiss francs. Money::from_minor builds an
amount 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() and Currency::minor_digits().

Desired behavior:

round_to_increment(self, increment: Decimal, strategy: RoundingMode) -> Result<Money, MoneyError>

  • Rounds the amount to the nearest multiple of increment, breaking ties by
    strategy. Example: 3.33 CHF at increment 0.05 with HalfUp gives 3.35 CHF.
  • The result carries the increment's decimal places: increment 1 gives 3,
    increment 1.00 gives 3.00.
  • Returns MoneyError::NonPositiveIncrement (new variant) if the increment is
    zero or negative. Diagnostic help: "use an increment above zero".
  • Returns MoneyError::Overflow if an intermediate value is too large for a
    Decimal (a large amount divided by a tiny increment).

to_minor(self, strategy: RoundingMode) -> Result<i64, MoneyError>

  • The amount in the currency's smallest units, as the inverse of from_minor:
    4.75 USD gives 475, 0.475 BHD gives 475.
  • Rounds to the currency's minor digits by strategy first, so sub-minor
    precision never errors: 1.005 USD with HalfUp gives 101.
  • Returns MoneyError::MinorUnitsOverflow (new variant) if the result is too
    large for an i64. Message: "the amount in minor units is too large for an
    i64". Diagnostic help states the i64 bound.

Both new MoneyError variants follow the existing pattern: thiserror
message, miette diagnostic code under lucre::money::, and a help note.

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 CHF
  • The result's decimal places match the increment's: increment 1 yields 3, increment 1.00 yields 3.00
  • A zero or negative increment returns MoneyError::NonPositiveIncrement
  • Money::from_minor(n, c).to_minor(strategy) returns Ok(n) for any strategy; an amount whose minor units exceed i64::MAX returns MoneyError::MinorUnitsOverflow
  • Both methods carry doctests in the style of the surrounding methods, and the fmtcheck, ci, and clippy mise tasks pass

Out of scope:

  • Directional rounding modes (always-up, always-down) on RoundingMode — separate issue if wanted
  • Changes to from_minor, round, or formatting
  • A minor-units accessor wider than i64
## Agent Brief **Category:** enhancement **Summary:** Add `Money::round_to_increment` and `Money::to_minor` **Current behavior:** `Money::round` rounds to a digit count only; there is no way to round to a cash increment such as 0.05 for Swiss francs. `Money::from_minor` builds an amount 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()` and `Currency::minor_digits()`. **Desired behavior:** `round_to_increment(self, increment: Decimal, strategy: RoundingMode) -> Result<Money, MoneyError>` - Rounds the amount to the nearest multiple of `increment`, breaking ties by `strategy`. Example: 3.33 CHF at increment 0.05 with `HalfUp` gives 3.35 CHF. - The result carries the increment's decimal places: increment `1` gives `3`, increment `1.00` gives `3.00`. - Returns `MoneyError::NonPositiveIncrement` (new variant) if the increment is zero or negative. Diagnostic help: "use an increment above zero". - Returns `MoneyError::Overflow` if an intermediate value is too large for a `Decimal` (a large amount divided by a tiny increment). `to_minor(self, strategy: RoundingMode) -> Result<i64, MoneyError>` - The amount in the currency's smallest units, as the inverse of `from_minor`: 4.75 USD gives 475, 0.475 BHD gives 475. - Rounds to the currency's minor digits by `strategy` first, so sub-minor precision never errors: 1.005 USD with `HalfUp` gives 101. - Returns `MoneyError::MinorUnitsOverflow` (new variant) if the result is too large for an `i64`. Message: "the amount in minor units is too large for an `i64`". Diagnostic help states the `i64` bound. Both new `MoneyError` variants follow the existing pattern: `thiserror` message, `miette` diagnostic code under `lucre::money::`, and a `help` note. **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 CHF - [ ] The result's decimal places match the increment's: increment `1` yields `3`, increment `1.00` yields `3.00` - [ ] A zero or negative increment returns `MoneyError::NonPositiveIncrement` - [ ] `Money::from_minor(n, c).to_minor(strategy)` returns `Ok(n)` for any strategy; an amount whose minor units exceed `i64::MAX` returns `MoneyError::MinorUnitsOverflow` - [ ] Both methods carry doctests in the style of the surrounding methods, and the `fmtcheck`, `ci`, and `clippy` mise tasks pass **Out of scope:** - Directional rounding modes (always-up, always-down) on `RoundingMode` — separate issue if wanted - Changes to `from_minor`, `round`, or formatting - A minor-units accessor wider than `i64`
rosa closed this issue 2026-08-17 15:11:47 +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#42
No description provided.