Enum `RoundMode`

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 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 Clone for RoundMode`

fn clone(self: &Self) -> RoundMode

`impl Copy for RoundMode`

`impl Debug for RoundMode`

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

`impl Eq for RoundMode`

`impl Freeze for RoundMode`

`impl Hash for RoundMode`

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

`impl PartialEq for RoundMode`

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

`impl RefUnwindSafe for RoundMode`

`impl Send for RoundMode`

`impl StructuralPartialEq for RoundMode`

`impl Sync for RoundMode`

`impl Unpin for RoundMode`

`impl UnsafeUnpin for RoundMode`

`impl UnwindSafe for RoundMode`

`impl<T> Any for RoundMode`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for RoundMode`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for RoundMode`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for RoundMode`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for RoundMode`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for RoundMode`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for RoundMode`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for RoundMode`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for RoundMode`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>