impl DateDifference

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

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.

This defaults to Unit::Day.

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 unit set must also be a calendar unit. Using a time unit 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());

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

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 or Unit::Day, whichever is greater. 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.

The unit set must also be a calendar unit. Using a time unit 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());

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

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

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

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.

Errors

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

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