pub struct DateDifference { /* private fields */ }Expand description
Options for Date::since and Date::until.
This type provides a way to configure the calculation of spans between two
Date values. In particular, both Date::since and Date::until accept
anything that implements Into<DateDifference>. There are a few key trait
implementations that make this convenient:
From<Date> for DateDifferencewill construct a configuration consisting of just the date. So for example,date1.until(date2)will return the span fromdate1todate2.From<DateTime> for DateDifferencewill construct a configuration consisting of just the date from the given datetime. So for example,date.since(datetime)returns the span fromdatetime.date()todate.From<(Unit, Date)>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 toDateDifference::new(date).largest(unit).From<(Unit, DateTime)>is like the one above, but with the date from the given datetime.
One can also provide a DateDifference value directly. Doing so is
necessary to use the rounding features of calculating a span. For example,
setting the smallest unit (defaults to Unit::Day), 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
Date::since, the reference date can be set automatically based on
the input to Date::since.
§Example
This example shows how to round a span between two date to the nearest year, with ties breaking away from zero.
use jiff::{civil::{Date, DateDifference}, RoundMode, ToSpan, Unit};
let d1 = "2024-03-15".parse::<Date>()?;
let d2 = "2030-09-13".parse::<Date>()?;
let span = d1.until(
DateDifference::new(d2)
.smallest(Unit::Year)
.mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 6.years().fieldwise());
// If the span were one day longer, it would round up to 7 years.
let d2 = "2030-09-14".parse::<Date>()?;
let span = d1.until(
DateDifference::new(d2)
.smallest(Unit::Year)
.mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 7.years().fieldwise());
Implementations§
Source§impl DateDifference
impl DateDifference
Sourcepub fn new(date: Date) -> DateDifference
pub fn new(date: Date) -> DateDifference
Create a new default configuration for computing the span between
the given date and some other date (specified as the receiver in
Date::since or Date::until).
Sourcepub fn smallest(self, unit: Unit) -> DateDifference
pub fn smallest(self, unit: Unit) -> DateDifference
Set the smallest units allowed in the span returned.
When a largest unit is not specified, 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 date to the nearest number of weeks.
use jiff::{civil::{Date, DateDifference}, RoundMode, ToSpan, Unit};
let d1 = "2024-03-15".parse::<Date>()?;
let d2 = "2030-11-22".parse::<Date>()?;
let span = d1.until(
DateDifference::new(d2)
.smallest(Unit::Week)
.largest(Unit::Week)
.mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 349.weeks().fieldwise());
Sourcepub fn largest(self, unit: Unit) -> DateDifference
pub fn largest(self, unit: Unit) -> DateDifference
Set the largest units allowed in the span returned.
When a largest unit is not specified, 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::Day). 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 date to units no bigger than months.
use jiff::{civil::{Date, DateDifference}, ToSpan, Unit};
let d1 = "2024-03-15".parse::<Date>()?;
let d2 = "2030-11-22".parse::<Date>()?;
let span = d1.until(
DateDifference::new(d2).largest(Unit::Month),
)?;
assert_eq!(span, 80.months().days(7).fieldwise());
Sourcepub fn mode(self, mode: RoundMode) -> DateDifference
pub fn mode(self, mode: RoundMode) -> DateDifference
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 date
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::{Date, DateDifference}, RoundMode, ToSpan, Unit};
let d1 = "2024-01-15".parse::<Date>()?;
let d2 = "2024-08-16".parse::<Date>()?;
let span = d1.until(
DateDifference::new(d2)
.smallest(Unit::Month)
.mode(RoundMode::Ceil),
)?;
// Only 7 months and 1 day elapsed, but we asked to always round up!
assert_eq!(span, 8.months().fieldwise());
// Since `Ceil` always rounds toward positive infinity, the behavior
// flips for a negative span.
let span = d1.since(
DateDifference::new(d2)
.smallest(Unit::Month)
.mode(RoundMode::Ceil),
)?;
assert_eq!(span, -7.months().fieldwise());
Sourcepub fn increment(self, increment: i64) -> DateDifference
pub fn increment(self, increment: i64) -> DateDifference
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::Month, then a rounding increment of
2 would result in rounding in increments of every other month.
§Example
This shows how to round the span between two date to the nearest even month.
use jiff::{civil::{Date, DateDifference}, RoundMode, ToSpan, Unit};
let d1 = "2024-01-15".parse::<Date>()?;
let d2 = "2024-08-15".parse::<Date>()?;
let span = d1.until(
DateDifference::new(d2)
.smallest(Unit::Month)
.increment(2)
.mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 8.months().fieldwise());
// If our second date was just one day less, rounding would truncate
// down to 6 months!
let d2 = "2024-08-14".parse::<Date>()?;
let span = d1.until(
DateDifference::new(d2)
.smallest(Unit::Month)
.increment(2)
.mode(RoundMode::HalfExpand),
)?;
assert_eq!(span, 6.months().fieldwise());
Trait Implementations§
Source§impl Clone for DateDifference
impl Clone for DateDifference
Source§fn clone(&self) -> DateDifference
fn clone(&self) -> DateDifference
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more