Struct TimestampRound

pub struct TimestampRound { /* private fields */ }

Available on crate features dep_jiff and alloc only.

Options for Timestamp::round.

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

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

Note that in the default configuration, no rounding occurs.

Example

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

use jiff::{Timestamp, Unit};

let ts: Timestamp = "2024-06-20 16:24:59.5Z".parse()?;
assert_eq!(
    ts.round(Unit::Second)?.to_string(),
    // The second rounds up and causes minutes to increase.
    "2024-06-20T16:25:00Z",
);

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

use jiff::{RoundMode, Timestamp, TimestampRound, Unit};

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

Implementations

impl TimestampRound

pub fn new() -> TimestampRound

Create a new default configuration for rounding a Timestamp.

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

Set the smallest units allowed in the timestamp 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:30Z 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::{Timestamp, TimestampRound, Unit};

let ts: Timestamp = "2024-06-20T03:25:30Z".parse()?;
assert_eq!(
    ts.round(TimestampRound::new().smallest(Unit::Minute))?.to_string(),
    "2024-06-20T03:26:00Z",
);
// Or, utilize the `From<Unit> for TimestampRound` impl:
assert_eq!(
    ts.round(Unit::Minute)?.to_string(),
    "2024-06-20T03:26:00Z",
);

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

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

use jiff::{RoundMode, Timestamp, TimestampRound, Unit};

let ts: Timestamp = "2024-06-20 03:25:01Z".parse()?;
assert_eq!(
    ts.round(
        TimestampRound::new()
            .smallest(Unit::Minute)
            .mode(RoundMode::Ceil),
    )?.to_string(),
    "2024-06-20T03:26:00Z",
);

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

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, when combined with the smallest unit (which defaults to Unit::Nanosecond), must divide evenly into 86,400 seconds (one 24-hour civil day). For example, increments of both 45 seconds and 15 minutes are allowed, but 7 seconds and 25 minutes are both not allowed.

Example

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

use jiff::{RoundMode, Timestamp, TimestampRound, Unit};

let ts: Timestamp = "2024-06-20 03:24:59Z".parse()?;
assert_eq!(
    ts.round((Unit::Minute, 10))?.to_string(),
    "2024-06-20T03:20:00Z",
);

Trait Implementations

impl Clone for TimestampRound

fn clone(&self) -> TimestampRound

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TimestampRound

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

Formats the value using the given formatter.

impl Default for TimestampRound

fn default() -> TimestampRound

Returns the “default value” for a type.

impl From<(Unit, i64)> for TimestampRound

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

Converts to this type from the input type.

impl From<Unit> for TimestampRound

fn from(unit: Unit) -> TimestampRound

Converts to this type from the input type.

impl Copy for TimestampRound