impl TimestampDifference

fn new(timestamp: Timestamp) -> TimestampDifference

Create a new default configuration for computing the span between the given timestamp and some other time (specified as the receiver in Timestamp::since or Timestamp::until).

fn smallest(self, unit: Unit) -> TimestampDifference

Set the smallest units allowed in the span returned.

Errors

The smallest units must be no greater than the largest units. If this is violated, then computing a span with this configuration will result in an error.

The largest unit must also be no greater than Unit::Hour.

Example

This shows how to round a span between two timestamps to units no less than seconds.

use jiff::{RoundMode, Timestamp, TimestampDifference, ToSpan, Unit};

let ts1 = "2024-03-15 08:14:02.5001Z".parse::<Timestamp>()?;
let ts2 = "2024-03-15T08:16:03.0001Z".parse::<Timestamp>()?;
let span = ts1.until(
    TimestampDifference::new(ts2)
        .smallest(Unit::Second)
        .mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 121.seconds().fieldwise());

// Because of the rounding mode, a small less-than-1-second increase in
// the first timestamp can change the result of rounding.
let ts1 = "2024-03-15 08:14:02.5002Z".parse::<Timestamp>()?;
let span = ts1.until(
    TimestampDifference::new(ts2)
        .smallest(Unit::Second)
        .mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 120.seconds().fieldwise());

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

fn largest(self, unit: Unit) -> TimestampDifference

Set the largest units allowed in the span returned.

When a largest unit is not specified, computing a span between timestamps behaves as if it were set to Unit::Second. Unless TimestampDifference::smallest is bigger than Unit::Second, then the largest unit is set to the smallest unit.

Errors

The largest units, when set, must be at least as big as the smallest units (which defaults to Unit::Nanosecond). If this is violated, then computing a span with this configuration will result in an error.

The largest unit must also be no greater than Unit::Hour.

Example

This shows how to round a span between two timestamps to units no bigger than seconds.

use jiff::{Timestamp, TimestampDifference, ToSpan, Unit};

let ts1 = "2024-03-15 08:14Z".parse::<Timestamp>()?;
let ts2 = "2030-11-22 08:30Z".parse::<Timestamp>()?;
let span = ts1.until(
    TimestampDifference::new(ts2).largest(Unit::Second),
)?;
assert_eq!(format!("{span:#}"), "211076160s");

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

fn mode(self, mode: RoundMode) -> TimestampDifference

Set the rounding mode.

This defaults to RoundMode::Trunc since it's plausible that rounding "up" in the context of computing the span between two timestamps could be surprising in a number of cases. The RoundMode::HalfExpand mode corresponds to typical rounding you might have learned about in school. But a variety of other rounding modes exist.

Example

This shows how to always round "up" towards positive infinity.

use jiff::{RoundMode, Timestamp, TimestampDifference, ToSpan, Unit};

let ts1 = "2024-03-15 08:10Z".parse::<Timestamp>()?;
let ts2 = "2024-03-15 08:11Z".parse::<Timestamp>()?;
let span = ts1.until(
    TimestampDifference::new(ts2)
        .smallest(Unit::Hour)
        .mode(RoundMode::Ceil),
)?;
// Only one minute elapsed, but we asked to always round up!
assert_eq!(span, 1.hour().fieldwise());

// Since `Ceil` always rounds toward positive infinity, the behavior
// flips for a negative span.
let span = ts1.since(
    TimestampDifference::new(ts2)
        .smallest(Unit::Hour)
        .mode(RoundMode::Ceil),
)?;
assert_eq!(span, 0.hour().fieldwise());

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

fn increment(self, increment: i64) -> TimestampDifference

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 after the smallest unit configured (and must not be equivalent to it). 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).

In all cases, the increment must be greater than zero and less than or equal to 1_000_000_000.

The error will occur when computing the span, and not when setting the increment here.

Example

This shows how to round the span between two timestamps to the nearest 5 minute increment.

use jiff::{RoundMode, Timestamp, TimestampDifference, ToSpan, Unit};

let ts1 = "2024-03-15 08:19Z".parse::<Timestamp>()?;
let ts2 = "2024-03-15 12:52Z".parse::<Timestamp>()?;
let span = ts1.until(
    TimestampDifference::new(ts2)
        .smallest(Unit::Minute)
        .increment(5)
        .mode(RoundMode::HalfExpand),
)?;
assert_eq!(span.to_string(), "PT275M");

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