pub struct DateTimeDifference { /* private fields */ }Expand description
Options for DateTime::since and DateTime::until.
This type provides a way to configure the calculation of
spans between two DateTime values. In particular, both
DateTime::since and DateTime::until accept anything that implements
Into<DateTimeDifference>. There are a few key trait implementations that
make this convenient:
From<DateTime> for DateTimeDifferencewill construct a configuration consisting of just the datetime. So for example,dt1.since(dt2)returns the span fromdt2todt1.From<Date> for DateTimeDifferencewill construct a configuration consisting of just the datetime built from the date given at midnight on that day.From<(Unit, DateTime)>is a convenient way to specify the largest units that should be present on the span returned. By default, the largest units are days. Using this trait implementation is equivalent toDateTimeDifference::new(datetime).largest(unit).From<(Unit, Date)>is like the one above, but with the time component fixed to midnight.
One can also provide a DateTimeDifference value directly. Doing so
is necessary to use the rounding features of calculating a span. For
example, setting the smallest unit (defaults to Unit::Nanosecond), the
rounding mode (defaults to RoundMode::Trunc) and the rounding increment
(defaults to 1). The defaults are selected such that no rounding occurs.
Rounding a span as part of calculating it is provided as a convenience.
Callers may choose to round the span as a distinct step via
Span::round, but callers may need to provide a reference date
for rounding larger units. By coupling rounding with routines like
DateTime::since, the reference date can be set automatically based on
the input to DateTime::since.
§Example
This example shows how to round a span between two datetimes to the nearest half-hour, with ties breaking away from zero.
use jiff::{civil::{DateTime, DateTimeDifference}, RoundMode, ToSpan, Unit};
let dt1 = "2024-03-15 08:14:00.123456789".parse::<DateTime>()?;
let dt2 = "2030-03-22 15:00".parse::<DateTime>()?;
let span = dt1.until(
DateTimeDifference::new(dt2)
.smallest(Unit::Minute)
.largest(Unit::Year)
.mode(RoundMode::HalfExpand)
.increment(30),
)?;
assert_eq!(span, 6.years().days(7).hours(7).fieldwise());
Implementations§
Source§impl DateTimeDifference
impl DateTimeDifference
Sourcepub fn new(datetime: DateTime) -> DateTimeDifference
pub fn new(datetime: DateTime) -> DateTimeDifference
Create a new default configuration for computing the span between the
given datetime and some other datetime (specified as the receiver in
DateTime::since or DateTime::until).
Sourcepub fn smallest(self, unit: Unit) -> DateTimeDifference
pub fn smallest(self, unit: Unit) -> DateTimeDifference
Set the smallest units allowed in the span returned.
When a largest unit is not specified and the smallest unit is days or greater, then the largest unit is automatically set to be equal to the smallest unit.
§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.
§Example
This shows how to round a span between two datetimes to the nearest number of weeks.
use jiff::{
civil::{DateTime, DateTimeDifference},
RoundMode, ToSpan, Unit,
};
let dt1 = "2024-03-15 08:14".parse::<DateTime>()?;
let dt2 = "2030-11-22 08:30".parse::<DateTime>()?;
let span = dt1.until(
DateTimeDifference::new(dt2)
.smallest(Unit::Week)
.largest(Unit::Week)
.mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 349.weeks().fieldwise());
Sourcepub fn largest(self, unit: Unit) -> DateTimeDifference
pub fn largest(self, unit: Unit) -> DateTimeDifference
Set the largest units allowed in the span returned.
When a largest unit is not specified and the smallest unit is days or greater, then the largest unit is automatically set to be equal to the smallest unit. Otherwise, when the largest unit is not specified, it is set to days.
Once a largest unit is set, there is no way to change this rounding configuration back to using the “automatic” default. Instead, callers must create a new configuration.
§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.
§Example
This shows how to round a span between two datetimes to units no bigger than seconds.
use jiff::{civil::{DateTime, DateTimeDifference}, ToSpan, Unit};
let dt1 = "2024-03-15 08:14".parse::<DateTime>()?;
let dt2 = "2030-11-22 08:30".parse::<DateTime>()?;
let span = dt1.until(
DateTimeDifference::new(dt2).largest(Unit::Second),
)?;
assert_eq!(span, 211076160.seconds().fieldwise());
Sourcepub fn mode(self, mode: RoundMode) -> DateTimeDifference
pub fn mode(self, mode: RoundMode) -> DateTimeDifference
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 datetimes 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::{
civil::{DateTime, DateTimeDifference},
RoundMode, ToSpan, Unit,
};
let dt1 = "2024-03-15 08:10".parse::<DateTime>()?;
let dt2 = "2024-03-15 08:11".parse::<DateTime>()?;
let span = dt1.until(
DateTimeDifference::new(dt2)
.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 = dt1.since(
DateTimeDifference::new(dt2)
.smallest(Unit::Hour)
.mode(RoundMode::Ceil),
)?;
assert_eq!(span, 0.hour().fieldwise());
Sourcepub fn increment(self, increment: i64) -> DateTimeDifference
pub fn increment(self, increment: i64) -> DateTimeDifference
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
When the smallest unit is less than days, 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).
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 datetimes to the nearest 5 minute increment.
use jiff::{
civil::{DateTime, DateTimeDifference},
RoundMode, ToSpan, Unit,
};
let dt1 = "2024-03-15 08:19".parse::<DateTime>()?;
let dt2 = "2024-03-15 12:52".parse::<DateTime>()?;
let span = dt1.until(
DateTimeDifference::new(dt2)
.smallest(Unit::Minute)
.increment(5)
.mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 4.hour().minutes(35).fieldwise());
Trait Implementations§
Source§impl Clone for DateTimeDifference
impl Clone for DateTimeDifference
Source§fn clone(&self) -> DateTimeDifference
fn clone(&self) -> DateTimeDifference
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more