Struct TimeRound

pub struct TimeRound { /* private fields */ }

Available on crate features dep_jiff and alloc only.

Options for Time::round.

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

• From<Unit> for TimeRound will construct a rounding configuration that rounds to the unit given. Specifically, TimeRound::new().smallest(unit).
• From<(Unit, i64)> for TimeRound is like the one above, but also specifies the rounding increment for TimeRound::increment.

Note that in the default configuration, no rounding occurs.

Example

This example shows how to round a time to the nearest second:

use jiff::{civil::{Time, time}, Unit};

let t: Time = "16:24:59.5".parse()?;
assert_eq!(
    t.round(Unit::Second)?,
    // The second rounds up and causes minutes to increase.
    time(16, 25, 0, 0),
);

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

use jiff::{civil::{Time, TimeRound, time}, RoundMode, Unit};

let t: Time = "2024-06-20 16:24:59.5".parse()?;
assert_eq!(
    t.round(
        TimeRound::new().smallest(Unit::Second).mode(RoundMode::Trunc),
    )?,
    // The second just gets truncated as if it wasn't there.
    time(16, 24, 59, 0),
);

Implementations

impl TimeRound

pub fn new() -> TimeRound

Create a new default configuration for rounding a Time.

pub fn smallest(self, unit: Unit) -> TimeRound

Set the smallest units allowed in the time 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 03:25:30 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::Hour.

Example

use jiff::{civil::{TimeRound, time}, Unit};

let t = time(3, 25, 30, 0);
assert_eq!(
    t.round(TimeRound::new().smallest(Unit::Minute))?,
    time(3, 26, 0, 0),
);
// Or, utilize the `From<Unit> for TimeRound` impl:
assert_eq!(t.round(Unit::Minute)?, time(3, 26, 0, 0));

pub fn mode(self, mode: RoundMode) -> TimeRound

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 times up towards positive infinity.

use jiff::{civil::{Time, TimeRound, time}, RoundMode, Unit};

let t: Time = "03:25:01".parse()?;
assert_eq!(
    t.round(
        TimeRound::new()
            .smallest(Unit::Minute)
            .mode(RoundMode::Ceil),
    )?,
    time(3, 26, 0, 0),
);

pub fn increment(self, increment: i64) -> TimeRound

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

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 time to the nearest 10 minute increment.

use jiff::{civil::{Time, TimeRound, time}, RoundMode, Unit};

let t: Time = "03:24:59".parse()?;
assert_eq!(t.round((Unit::Minute, 10))?, time(3, 20, 0, 0));

Trait Implementations

impl Clone for TimeRound

fn clone(&self) -> TimeRound

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TimeRound

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

Formats the value using the given formatter.

impl Default for TimeRound

fn default() -> TimeRound

Returns the “default value” for a type.

impl From<(Unit, i64)> for TimeRound

fn from(_: (Unit, i64)) -> TimeRound

Converts to this type from the input type.

impl From<Unit> for TimeRound

fn from(unit: Unit) -> TimeRound

Converts to this type from the input type.

impl Copy for TimeRound