Directional rounding modes for RoundingMode #46
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#46
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
RoundingModeoffers only tie-breaking rules:HalfUp,HalfDown,HalfEven. Some contexts round in one direction regardless of the digit being dropped:With #42's
round_to_incrementandto_minortaking aRoundingMode, the gap now spans three methods.Proposal
Add directional variants to
RoundingMode.rust_decimalalready implements the candidates:AwayFromZero,ToZero,ToNegativeInfinity,ToPositiveInfinity.Open questions
Up/Downcollide with the existingHalfUp/HalfDownsense of "up" and read ambiguously for negative amounts. Something explicit likeAwayFromZero/TowardZeromay be clearer.Agent Brief
Category: enhancement
Summary: Add four directional variants to
RoundingModeand rename the three existing ones, so every variant is named after therust_decimalstrategy it maps to. Breaking change.Current behavior:
RoundingModehas three variants —HalfUp,HalfDown,HalfEven— all ofwhich decide only what happens at an exact midpoint. Every rounding path in the
crate (
Money::round,Money::round_to_increment,Money::to_minor, andFormat::precision) takes aRoundingModeand routes it through one privatemapping onto a
rust_decimal::RoundingStrategy. A caller who needs to round ina 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:
RoundingModebecomes a one-to-one naming ofrust_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.
rust_decimal::RoundingStrategyMidpointAwayFromZeroMidpointAwayFromZero0.125→0.13,-0.125→-0.13HalfUpMidpointTowardZeroMidpointTowardZero0.125→0.12,-0.125→-0.12HalfDownMidpointNearestEvenMidpointNearestEven0.125→0.12,0.135→0.14HalfEvenAwayFromZeroAwayFromZero1.1→2,-1.1→-2ToZeroToZero1.9→1,-1.9→-1ToPositiveInfinityToPositiveInfinity1.1→2,-1.9→-1ToNegativeInfinityToNegativeInfinity1.9→1,-1.1→-2The renames change behavior for nobody:
HalfUpandMidpointAwayFromZeroround identically. Only the spelling moves. Do not introduce
Up/Down/Ceiling/Floorspellings for the directional variants.Every method that already takes a
RoundingModeaccepts the new variants withno signature change and no extra error case.
Money::round_to_incrementroundsthe amount divided by the increment, so a directional variant rounds the step
count in that direction; its
NonPositiveIncrementandOverflowconditionsare unchanged.
Breaking change: both the Rust API and the serde wire format. Any caller
naming
RoundingMode::HalfUpand any storedFormatdocument containing"half-up"stops working. The old serde strings are not kept as acceptedaliases — 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 doccurrently 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.
RoundingMode→rust_decimal::RoundingStrategymapping — thesingle place every arm lives. After the rename each arm maps a variant to
the identically named strategy.
Serialize/DeserializeforRoundingMode— 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 keepbeing rejected, and the visitor's expectation message must list all seven.
Formatserde examples across the crate spellRoundingModevariants and the
"half-up"string literal. Every one has to move to the newnames, including the serialized-
Formatexample that embeds the roundingstring in a JSON document.
propteststrategies that pick aRoundingModein the integration testsuites — each enumerates the three variants by hand and must list all seven,
or the property tests silently stop covering the new modes.
Acceptance criteria:
RoundingModehas exactly the seven variants named above, and no variantkeeps a
Half*name.positive and negative amounts alike.
Money::round,Money::round_to_increment,Money::to_minor, andFormat::precisionall accept each new variant and round by it.negative amount, proving
AwayFromZeroandToPositiveInfinitydifferon negatives, and that
ToZeroandToNegativeInfinitydiffer onnegatives.
round_to_incrementwith a directional variant, showingthe amount lands on a multiple of the increment in the named direction.
an unknown string and the retired
"half-up"fail to deserialize.proptestRoundingModestrategies pick from all seven variants.about midpoints, and every variant carries a doc comment.
mise run fmtcheck,mise run clippy, andmise run cipass.Out of scope:
behavior change.
Half*names or the old serde strings as deprecated aliases.rust_decimaldoes not implement, such as a half-toward-negative-infinity rule or stochastic rounding.
Defaultimpl forRoundingMode, or making the mode optional at any callsite.
FromStrimpl —RoundingModeis parsed only through serde today, andthat stays true.