Struct TimestampRound

struct TimestampRound { ... }

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:

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

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

impl Clone for TimestampRound

fn clone(self: &Self) -> TimestampRound

impl Copy for TimestampRound

impl Debug for TimestampRound

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

impl Default for TimestampRound

fn default() -> TimestampRound

impl Freeze for TimestampRound

impl From for TimestampRound

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

impl From for TimestampRound

fn from(unit: Unit) -> TimestampRound

impl RefUnwindSafe for TimestampRound

impl Send for TimestampRound

impl Sync for TimestampRound

impl Unpin for TimestampRound

impl UnsafeUnpin for TimestampRound

impl UnwindSafe for TimestampRound

impl<T> Any for TimestampRound

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for TimestampRound

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

impl<T> BorrowMut for TimestampRound

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

impl<T> CloneToUninit for TimestampRound

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

impl<T> From for TimestampRound

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for TimestampRound

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

impl<T, U> Into for TimestampRound

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 TimestampRound

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

impl<T, U> TryInto for TimestampRound

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