rustmax::jiff::civil

Struct DateTimeDifference

Source
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 DateTimeDifference will construct a configuration consisting of just the datetime. So for example, dt1.since(dt2) returns the span from dt2 to dt1.
  • From<Date> for DateTimeDifference will 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 to DateTimeDifference::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

Source

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

Source

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

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

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

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

Source§

fn clone(&self) -> DateTimeDifference

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for DateTimeDifference

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl<'a> From<&'a Zoned> for DateTimeDifference

Source§

fn from(zdt: &'a Zoned) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl<'a> From<(Unit, &'a Zoned)> for DateTimeDifference

Source§

fn from(_: (Unit, &'a Zoned)) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl From<(Unit, Date)> for DateTimeDifference

Source§

fn from(_: (Unit, Date)) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl From<(Unit, DateTime)> for DateTimeDifference

Source§

fn from(_: (Unit, DateTime)) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl From<(Unit, Zoned)> for DateTimeDifference

Source§

fn from(_: (Unit, Zoned)) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl From<Date> for DateTimeDifference

Source§

fn from(date: Date) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl From<DateTime> for DateTimeDifference

Source§

fn from(dt: DateTime) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl From<Zoned> for DateTimeDifference

Source§

fn from(zdt: Zoned) -> DateTimeDifference

Converts to this type from the input type.
Source§

impl Copy for DateTimeDifference

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> FromRef<T> for T
where T: Clone,

Source§

fn from_ref(input: &T) -> T

Converts to this type from a reference to the input type.
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize = _

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> QuickClone<T> for T
where T: Clone,

Source§

fn C(&self) -> T

Source§

impl<T> QuickToOwned for T
where T: ToOwned,

Source§

type Owned = <T as ToOwned>::Owned

Source§

fn O(&self) -> <T as QuickToOwned>::Owned

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,

Source§

impl<T> MaybeSendSync for T