Directional rounding modes for RoundingMode #46

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

Problem

RoundingMode offers only tie-breaking rules: HalfUp, HalfDown, HalfEven. Some contexts round in one direction regardless of the digit being dropped:

  • Tax rules in some jurisdictions require rounding the tax amount always down (or always up).
  • Cash rounding at the till sometimes rounds in the merchant's or customer's favor by rule, not to nearest.
  • Truncation toward zero is a common ledger convention.

With #42's round_to_increment and to_minor taking a RoundingMode, the gap now spans three methods.

Proposal

Add directional variants to RoundingMode. rust_decimal already implements the candidates: AwayFromZero, ToZero, ToNegativeInfinity, ToPositiveInfinity.

Open questions

  • Which set: the zero-relative pair, the infinity-relative pair, or all four.
  • Naming: Up/Down collide with the existing HalfUp/HalfDown sense of "up" and read ambiguously for negative amounts. Something explicit like AwayFromZero/TowardZero may be clearer.
  • Whether existing callers rounding negative amounts expect zero-relative or infinity-relative behavior from the new modes.
## Problem `RoundingMode` offers only tie-breaking rules: `HalfUp`, `HalfDown`, `HalfEven`. Some contexts round in one direction regardless of the digit being dropped: - Tax rules in some jurisdictions require rounding the tax amount always down (or always up). - Cash rounding at the till sometimes rounds in the merchant's or customer's favor by rule, not to nearest. - Truncation toward zero is a common ledger convention. With #42's `round_to_increment` and `to_minor` taking a `RoundingMode`, the gap now spans three methods. ## Proposal Add directional variants to `RoundingMode`. `rust_decimal` already implements the candidates: `AwayFromZero`, `ToZero`, `ToNegativeInfinity`, `ToPositiveInfinity`. ## Open questions - Which set: the zero-relative pair, the infinity-relative pair, or all four. - Naming: `Up`/`Down` collide with the existing `HalfUp`/`HalfDown` sense of "up" and read ambiguously for negative amounts. Something explicit like `AwayFromZero`/`TowardZero` may be clearer. - Whether existing callers rounding negative amounts expect zero-relative or infinity-relative behavior from the new modes.
Author
Owner

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add four directional variants to RoundingMode and rename the three existing ones, so every variant is named after the rust_decimal strategy it maps to. Breaking change.

Current behavior:

RoundingMode has three variants — HalfUp, HalfDown, HalfEven — all of
which decide only what happens at an exact midpoint. Every rounding path in the
crate (Money::round, Money::round_to_increment, Money::to_minor, and
Format::precision) takes a RoundingMode and routes it through one private
mapping onto a rust_decimal::RoundingStrategy. A caller who needs to round in
a fixed direction regardless of the dropped digit — truncation toward zero, tax
always down, cash always up — cannot express it and has to round outside the
crate.

Desired behavior:

RoundingMode becomes a one-to-one naming of rust_decimal::RoundingStrategy.
Every variant takes that strategy's name, and each name states its own
direction — which settles the issue's open question about negative amounts,
because the variant says what it does to one.

Variant rust_decimal::RoundingStrategy Effect Replaces
MidpointAwayFromZero MidpointAwayFromZero 0.125 → 0.13, -0.125 → -0.13 HalfUp
MidpointTowardZero MidpointTowardZero 0.125 → 0.12, -0.125 → -0.12 HalfDown
MidpointNearestEven MidpointNearestEven 0.125 → 0.12, 0.135 → 0.14 HalfEven
AwayFromZero AwayFromZero 1.1 → 2, -1.1 → -2 new
ToZero ToZero 1.9 → 1, -1.9 → -1 new
ToPositiveInfinity ToPositiveInfinity 1.1 → 2, -1.9 → -1 new
ToNegativeInfinity ToNegativeInfinity 1.9 → 1, -1.1 → -2 new

The renames change behavior for nobody: HalfUp and MidpointAwayFromZero
round identically. Only the spelling moves. Do not introduce
Up/Down/Ceiling/Floor spellings for the directional variants.

Every method that already takes a RoundingMode accepts the new variants with
no signature change and no extra error case. Money::round_to_increment rounds
the amount divided by the increment, so a directional variant rounds the step
count in that direction; its NonPositiveIncrement and Overflow conditions
are unchanged.

Breaking change: both the Rust API and the serde wire format. Any caller
naming RoundingMode::HalfUp and any stored Format document containing
"half-up" stops working. The old serde strings are not kept as accepted
aliases — deserializing "half-up" must fail like any other unknown string.
Land this as a feat! commit.

Key interfaces:

  • RoundingMode — a public #[non_exhaustive] enum. Its type-level doc
    currently says the enum decides what happens to a value that falls exactly
    halfway. That is no longer the whole story, so rewrite the summary to cover
    both kinds of rule. Every variant needs a doc comment naming what it does to
    a positive and to a negative example, in the style the three existing
    variants already use.
  • The private RoundingMode → rust_decimal::RoundingStrategy mapping — the
    single place every arm lives. After the rename each arm maps a variant to
    the identically named strategy.
  • Serialize / Deserialize for RoundingMode — hand-written, not derived,
    using kebab-case strings. The full set becomes
    "midpoint-away-from-zero", "midpoint-toward-zero",
    "midpoint-nearest-even", "away-from-zero", "to-zero",
    "to-positive-infinity", "to-negative-infinity". Unknown strings must keep
    being rejected, and the visitor's expectation message must list all seven.
  • Doctests and Format serde examples across the crate spell RoundingMode
    variants and the "half-up" string literal. Every one has to move to the new
    names, including the serialized-Format example that embeds the rounding
    string in a JSON document.
  • The proptest strategies that pick a RoundingMode in the integration test
    suites — each enumerates the three variants by hand and must list all seven,
    or the property tests silently stop covering the new modes.

Acceptance criteria:

  • RoundingMode has exactly the seven variants named above, and no variant
    keeps a Half* name.
  • The three renamed variants round exactly as their old spellings did, for
    positive and negative amounts alike.
  • Money::round, Money::round_to_increment, Money::to_minor, and
    Format::precision all accept each new variant and round by it.
  • A test covers each new directional variant against a positive and a
    negative amount, proving AwayFromZero and ToPositiveInfinity differ
    on negatives, and that ToZero and ToNegativeInfinity differ on
    negatives.
  • A test covers round_to_increment with a directional variant, showing
    the amount lands on a multiple of the increment in the named direction.
  • Each variant round-trips through serde as its kebab-case string, and both
    an unknown string and the retired "half-up" fail to deserialize.
  • The proptest RoundingMode strategies pick from all seven variants.
  • The enum's type-level doc no longer describes the enum as being only
    about midpoints, and every variant carries a doc comment.
  • mise run fmtcheck, mise run clippy, and mise run ci pass.

Out of scope:

  • Changing how the three renamed variants round. This is a rename, not a
    behavior change.
  • Keeping the old Half* names or the old serde strings as deprecated aliases.
  • Rounding rules rust_decimal does not implement, such as a half-toward-
    negative-infinity rule or stochastic rounding.
  • A Default impl for RoundingMode, or making the mode optional at any call
    site.
  • A FromStr impl — RoundingMode is parsed only through serde today, and
    that stays true.
  • Storing a per-currency or per-jurisdiction default rounding rule anywhere.
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Add four directional variants to `RoundingMode` and rename the three existing ones, so every variant is named after the `rust_decimal` strategy it maps to. Breaking change. **Current behavior:** `RoundingMode` has three variants — `HalfUp`, `HalfDown`, `HalfEven` — all of which decide only what happens at an exact midpoint. Every rounding path in the crate (`Money::round`, `Money::round_to_increment`, `Money::to_minor`, and `Format::precision`) takes a `RoundingMode` and routes it through one private mapping onto a `rust_decimal::RoundingStrategy`. A caller who needs to round in a fixed direction regardless of the dropped digit — truncation toward zero, tax always down, cash always up — cannot express it and has to round outside the crate. **Desired behavior:** `RoundingMode` becomes a one-to-one naming of `rust_decimal::RoundingStrategy`. Every variant takes that strategy's name, and each name states its own direction — which settles the issue's open question about negative amounts, because the variant says what it does to one. | Variant | `rust_decimal::RoundingStrategy` | Effect | Replaces | | ---------------------- | -------------------------------- | ---------------------------- | ----------- | | `MidpointAwayFromZero` | `MidpointAwayFromZero` | `0.125` → `0.13`, `-0.125` → `-0.13` | `HalfUp` | | `MidpointTowardZero` | `MidpointTowardZero` | `0.125` → `0.12`, `-0.125` → `-0.12` | `HalfDown` | | `MidpointNearestEven` | `MidpointNearestEven` | `0.125` → `0.12`, `0.135` → `0.14` | `HalfEven` | | `AwayFromZero` | `AwayFromZero` | `1.1` → `2`, `-1.1` → `-2` | new | | `ToZero` | `ToZero` | `1.9` → `1`, `-1.9` → `-1` | new | | `ToPositiveInfinity` | `ToPositiveInfinity` | `1.1` → `2`, `-1.9` → `-1` | new | | `ToNegativeInfinity` | `ToNegativeInfinity` | `1.9` → `1`, `-1.1` → `-2` | new | The renames change behavior for nobody: `HalfUp` and `MidpointAwayFromZero` round identically. Only the spelling moves. Do not introduce `Up`/`Down`/`Ceiling`/`Floor` spellings for the directional variants. Every method that already takes a `RoundingMode` accepts the new variants with no signature change and no extra error case. `Money::round_to_increment` rounds the amount divided by the increment, so a directional variant rounds the step count in that direction; its `NonPositiveIncrement` and `Overflow` conditions are unchanged. **Breaking change:** both the Rust API and the serde wire format. Any caller naming `RoundingMode::HalfUp` and any stored `Format` document containing `"half-up"` stops working. The old serde strings are **not** kept as accepted aliases — deserializing `"half-up"` must fail like any other unknown string. Land this as a `feat!` commit. **Key interfaces:** - `RoundingMode` — a public `#[non_exhaustive]` enum. Its type-level doc currently says the enum decides what happens to a value that falls exactly halfway. That is no longer the whole story, so rewrite the summary to cover both kinds of rule. Every variant needs a doc comment naming what it does to a positive and to a negative example, in the style the three existing variants already use. - The private `RoundingMode` → `rust_decimal::RoundingStrategy` mapping — the single place every arm lives. After the rename each arm maps a variant to the identically named strategy. - `Serialize` / `Deserialize` for `RoundingMode` — hand-written, not derived, using kebab-case strings. The full set becomes `"midpoint-away-from-zero"`, `"midpoint-toward-zero"`, `"midpoint-nearest-even"`, `"away-from-zero"`, `"to-zero"`, `"to-positive-infinity"`, `"to-negative-infinity"`. Unknown strings must keep being rejected, and the visitor's expectation message must list all seven. - Doctests and `Format` serde examples across the crate spell `RoundingMode` variants and the `"half-up"` string literal. Every one has to move to the new names, including the serialized-`Format` example that embeds the rounding string in a JSON document. - The `proptest` strategies that pick a `RoundingMode` in the integration test suites — each enumerates the three variants by hand and must list all seven, or the property tests silently stop covering the new modes. **Acceptance criteria:** - [ ] `RoundingMode` has exactly the seven variants named above, and no variant keeps a `Half*` name. - [ ] The three renamed variants round exactly as their old spellings did, for positive and negative amounts alike. - [ ] `Money::round`, `Money::round_to_increment`, `Money::to_minor`, and `Format::precision` all accept each new variant and round by it. - [ ] A test covers each new directional variant against a positive and a negative amount, proving `AwayFromZero` and `ToPositiveInfinity` differ on negatives, and that `ToZero` and `ToNegativeInfinity` differ on negatives. - [ ] A test covers `round_to_increment` with a directional variant, showing the amount lands on a multiple of the increment in the named direction. - [ ] Each variant round-trips through serde as its kebab-case string, and both an unknown string and the retired `"half-up"` fail to deserialize. - [ ] The `proptest` `RoundingMode` strategies pick from all seven variants. - [ ] The enum's type-level doc no longer describes the enum as being only about midpoints, and every variant carries a doc comment. - [ ] `mise run fmtcheck`, `mise run clippy`, and `mise run ci` pass. **Out of scope:** - Changing how the three renamed variants round. This is a rename, not a behavior change. - Keeping the old `Half*` names or the old serde strings as deprecated aliases. - Rounding rules `rust_decimal` does not implement, such as a half-toward- negative-infinity rule or stochastic rounding. - A `Default` impl for `RoundingMode`, or making the mode optional at any call site. - A `FromStr` impl — `RoundingMode` is parsed only through serde today, and that stays true. - Storing a per-currency or per-jurisdiction default rounding rule anywhere.
rosa closed this issue 2026-08-21 22:04:54 +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#46
No description provided.