Enum RoundMode 

#[non_exhaustive]
pub enum RoundMode {
    Ceil,
    Floor,
    Expand,
    Trunc,
    HalfCeil,
    HalfFloor,
    HalfExpand,
    HalfTrunc,
    HalfEven,
}

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)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

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

impl RoundMode

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.

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.

Trait Implementations

impl Clone for RoundMode

fn clone(&self) -> RoundMode

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RoundMode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for RoundMode

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for RoundMode

fn eq(&self, other: &RoundMode) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for RoundMode

impl Eq for RoundMode

impl StructuralPartialEq for RoundMode