#[non_exhaustive]pub enum RoundMode {
Ceil,
Floor,
Expand,
Trunc,
HalfCeil,
HalfFloor,
HalfExpand,
HalfTrunc,
HalfEven,
}Expand description
The mode for dealing with the remainder when rounding datetimes or spans.
This is used in APIs like Span::round for rounding
spans, and APIs like Zoned::round for rounding
datetimes.
In the documentation for each variant, we refer to concepts like the
“smallest” unit and the “rounding increment.” These are best described
in the documentation for what you’re rounding. For example,
SpanRound::smallest
and SpanRound::increment.
§Example
This shows how to round a span with a different rounding mode than the default:
use jiff::{RoundMode, SpanRound, ToSpan, Unit};
// The default rounds like how you were taught in school:
assert_eq!(
1.hour().minutes(59).round(Unit::Hour)?,
2.hours().fieldwise(),
);
// But we can change the mode, e.g., truncation:
let options = SpanRound::new().smallest(Unit::Hour).mode(RoundMode::Trunc);
assert_eq!(
1.hour().minutes(59).round(options)?,
1.hour().fieldwise(),
);
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
Ceil
Rounds toward positive infinity.
For negative spans and datetimes, this option will make the value
smaller, which could be unexpected. To round away from zero, use
Expand.
Floor
Rounds toward negative infinity.
This mode acts like Trunc for positive spans and datetimes, but
for negative values it will make the value larger, which could be
unexpected. To round towards zero, use Trunc.
Expand
Rounds away from zero like Ceil for positive spans and datetimes,
and like Floor for negative spans and datetimes.
Trunc
Rounds toward zero, chopping off any fractional part of a unit.
This is the default when rounding spans returned from
datetime arithmetic. (But it is not the default for
Span::round.)
HalfCeil
Rounds to the nearest allowed value like HalfExpand, but when there
is a tie, round towards positive infinity like Ceil.
HalfFloor
Rounds to the nearest allowed value like HalfExpand, but when there
is a tie, round towards negative infinity like Floor.
HalfExpand
Rounds to the nearest value allowed by the rounding increment and the
smallest unit. When there is a tie, round away from zero like Ceil
for positive spans and datetimes and like Floor for negative spans
and datetimes.
This corresponds to how rounding is often taught in school.
This is the default for rounding spans and datetimes.
HalfTrunc
Rounds to the nearest allowed value like HalfExpand, but when there
is a tie, round towards zero like Trunc.
HalfEven
Rounds to the nearest allowed value like HalfExpand, but when there
is a tie, round towards the value that is an even multiple of the
rounding increment. For example, with a rounding increment of 3,
the number 10 would round up to 12 instead of down to 9, because
12 is an even multiple of 3, where as 9 is is an odd multiple.
Implementations§
Source§impl RoundMode
impl RoundMode
Sourcepub(crate) fn round_by_duration(
self,
quantity: SignedDuration,
increment: SignedDuration,
) -> Result<SignedDuration, Error>
pub(crate) fn round_by_duration( self, quantity: SignedDuration, increment: SignedDuration, ) -> Result<SignedDuration, Error>
Round quantity to the nearest increment using this rounding mode.
If this the rounding result would overflow SignedDuration, then an
error is returned.
Callers should generally prefer higher level APIs. But this one is unavoidable when the increment isn’t tied to an invariant length and can vary.
§Panics
Callers must ensure that increment has a number of nanoseconds
greater than or equal to 1.
Sourcefn round_by_i128(self, quantity: i128, increment: i128) -> i128
fn round_by_i128(self, quantity: i128, increment: i128) -> i128
The internal API that does the actual rounding.
This does not error on overflow because callers can never use values
close to the i128 limits. If an overflow would otherwise occur due to
rounding, then it saturates instead of panicking or returning an error.
I wish we could do modulus on SignedDuration directly. Then we
wouldn’t need 128-bit arithmetic at all. But I looked into making
SignedDuration % SignedDuration work, and it was quite involved? So I
guess we should just let the compiler handle it for i128. We’d also
need division.
§Panics
When increment < 1.