Struct ZonedRound

struct ZonedRound { ... }

Options for Zoned::round.

This type provides a way to configure the rounding of a zoned datetime. In particular, Zoned::round accepts anything that implements the Into<ZonedRound> trait. There are some trait implementations that therefore make calling Zoned::round in some common cases more ergonomic:

Note that in the default configuration, no rounding occurs.

Example

This example shows how to round a zoned datetime to the nearest second:

use jiff::{civil::date, Unit, Zoned};

let zdt: Zoned = "2024-06-20 16:24:59.5[America/New_York]".parse()?;
assert_eq!(
    zdt.round(Unit::Second)?,
    // The second rounds up and causes minutes to increase.
    date(2024, 6, 20).at(16, 25, 0, 0).in_tz("America/New_York")?,
);

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

The above makes use of the fact that Unit implements Into<ZonedRound>. If you want to change the rounding mode to, say, truncation, then you'll need to construct a ZonedRound explicitly since there are no convenience Into trait implementations for RoundMode.

use jiff::{civil::date, RoundMode, Unit, Zoned, ZonedRound};

let zdt: Zoned = "2024-06-20 16:24:59.5[America/New_York]".parse()?;
assert_eq!(
    zdt.round(
        ZonedRound::new().smallest(Unit::Second).mode(RoundMode::Trunc),
    )?,
    // The second just gets truncated as if it wasn't there.
    date(2024, 6, 20).at(16, 24, 59, 0).in_tz("America/New_York")?,
);

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

Implementations

impl ZonedRound

fn new() -> ZonedRound

Create a new default configuration for rounding a Zoned.

fn smallest(self: Self, unit: Unit) -> ZonedRound

Set the smallest units allowed in the zoned datetime returned after rounding.

Any units below the smallest configured unit will be used, along with the rounding increment and rounding mode, to determine the value of the smallest unit. For example, when rounding 2024-06-20T03:25:30[America/New_York] to the nearest minute, the 30 second unit will result in rounding the minute unit of 25 up to 26 and zeroing out everything below minutes.

This defaults to Unit::Nanosecond.

Errors

The smallest units must be no greater than Unit::Day. And when the smallest unit is Unit::Day, the rounding increment must be equal to 1. Otherwise an error will be returned from Zoned::round.

Example

use jiff::{civil::date, Unit, ZonedRound};

let zdt = date(2024, 6, 20).at(3, 25, 30, 0).in_tz("America/New_York")?;
assert_eq!(
    zdt.round(ZonedRound::new().smallest(Unit::Minute))?,
    date(2024, 6, 20).at(3, 26, 0, 0).in_tz("America/New_York")?,
);
// Or, utilize the `From<Unit> for ZonedRound` impl:
assert_eq!(
    zdt.round(Unit::Minute)?,
    date(2024, 6, 20).at(3, 26, 0, 0).in_tz("America/New_York")?,
);

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

fn mode(self: Self, mode: RoundMode) -> ZonedRound

Set the rounding mode.

This defaults to RoundMode::HalfExpand, which rounds away from zero. It matches the kind of rounding you might have been taught in school.

Example

This shows how to always round zoned datetimes up towards positive infinity.

use jiff::{civil::date, RoundMode, Unit, Zoned, ZonedRound};

let zdt: Zoned = "2024-06-20 03:25:01[America/New_York]".parse()?;
assert_eq!(
    zdt.round(
        ZonedRound::new()
            .smallest(Unit::Minute)
            .mode(RoundMode::Ceil),
    )?,
    date(2024, 6, 20).at(3, 26, 0, 0).in_tz("America/New_York")?,
);

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

fn increment(self: Self, increment: i64) -> ZonedRound

Set the rounding increment for the smallest unit.

The default value is 1. Other values permit rounding the smallest unit to the nearest integer increment specified. For example, if the smallest unit is set to Unit::Minute, then a rounding increment of 30 would result in rounding in increments of a half hour. That is, the only minute value that could result would be 0 or 30.

Errors

When the smallest unit is Unit::Day, then the rounding increment must be 1 or else Zoned::round will return an error.

For other units, the rounding increment must divide evenly into the next highest unit above the smallest unit set. The rounding increment must also not be equal to the next highest unit. For example, if the smallest unit is Unit::Nanosecond, then some of the valid values for the rounding increment are 1, 2, 4, 5, 100 and 500. Namely, any integer that divides evenly into 1,000 nanoseconds since there are 1,000 nanoseconds in the next highest unit (microseconds).

Example

This example shows how to round a zoned datetime to the nearest 10 minute increment.

use jiff::{civil::date, RoundMode, Unit, Zoned, ZonedRound};

let zdt: Zoned = "2024-06-20 03:24:59[America/New_York]".parse()?;
assert_eq!(
    zdt.round((Unit::Minute, 10))?,
    date(2024, 6, 20).at(3, 20, 0, 0).in_tz("America/New_York")?,
);

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

impl Clone for ZonedRound

fn clone(self: &Self) -> ZonedRound

impl Copy for ZonedRound

impl Debug for ZonedRound

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

impl Default for ZonedRound

fn default() -> ZonedRound

impl Freeze for ZonedRound

impl From for ZonedRound

fn from((unit, increment): (Unit, i64)) -> ZonedRound

impl From for ZonedRound

fn from(unit: Unit) -> ZonedRound

impl RefUnwindSafe for ZonedRound

impl Send for ZonedRound

impl Sync for ZonedRound

impl Unpin for ZonedRound

impl UnsafeUnpin for ZonedRound

impl UnwindSafe for ZonedRound

impl<T> Any for ZonedRound

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for ZonedRound

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

impl<T> BorrowMut for ZonedRound

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

impl<T> CloneToUninit for ZonedRound

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

impl<T> From for ZonedRound

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for ZonedRound

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

impl<T, U> Into for ZonedRound

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 ZonedRound

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

impl<T, U> TryInto for ZonedRound

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