Enum `RoundMode`

#[non_exhaustive]
pub enum RoundMode

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(),
);

# Ok::<(), Box<dyn std::error::Error>>(())

Variants

Ceil

Rounds toward positive infinity.

For negative spans and datetimes, this option will make the absolute 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 absolute 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.