Struct `TimestampRound`

pub struct TimestampRound { /* private fields */ }

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

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

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

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

Implementations

`impl TimestampRound`

fn new() -> TimestampRound

Create a new default configuration for rounding a Timestamp.

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

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

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

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

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.

In all cases, the increment must be greater than zero and less than or equal to 1_000_000_000. Note that this means, for example, one cannot round to the nearest 43_200_000_000_000 nanosecond, despite the fact that it divides evenly into 86_400_000_000_000 seconds.

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

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