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.

Trait Implementations

impl Clone for RoundMode

fn clone(&self) -> RoundMode

Returns a copy 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<(), Error>

Formats the value using the given formatter.

impl Hash for RoundMode

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

where __H: Hasher,

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