devela::_dep::jiff::civil

Struct DateDifference

pub struct DateDifference { /* private fields */ }

Available on crate features dep_jiff and alloc only.

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 DateDifference will construct a configuration consisting of just the date. So for example, date1.until(date2) will return the span from date1 to date2.
From<DateTime> for DateDifference will construct a configuration consisting of just the date from the given datetime. So for example, date.since(datetime) returns the span from datetime.date() to date.
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 to DateDifference::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());

// 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());

Implementations§

§

impl 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).

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());

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

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());

// 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());

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());

// 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());