Struct SpanRelativeTo

struct SpanRelativeTo<'a> { ... }

A relative datetime for use with Span APIs.

A relative datetime can be one of the following: civil::Date, civil::DateTime or Zoned. It can be constructed from any of the preceding types via From trait implementations.

A relative datetime is used to indicate how the calendar units of a Span should be interpreted. For example, the span "1 month" does not have a fixed meaning. One month from 2024-03-01 is 31 days, but one month from 2024-04-01 is 30 days. Similar for years.

When a relative datetime in time zone aware (i.e., it is a Zoned), then a Span will also consider its day units to be variable in length. For example, 2024-03-10 in America/New_York was only 23 hours long, where as 2024-11-03 in America/New_York was 25 hours long. When a relative datetime is civil, then days are considered to always be of a fixed 24 hour length.

This type is principally used as an input to one of several different Span APIs:

Example

This example shows how to round a span with larger calendar units to smaller units:

use jiff::{SpanRound, ToSpan, Unit, Zoned};

let zdt: Zoned = "2012-01-01[Antarctica/Troll]".parse()?;
let round = SpanRound::new().largest(Unit::Day).relative(&zdt);
assert_eq!(1.year().round(round)?, 366.days().fieldwise());

// If you tried this without a relative datetime, it would fail:
let round = SpanRound::new().largest(Unit::Day);
assert!(1.year().round(round).is_err());

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

Implementations

impl<'a> SpanRelativeTo<'a>

const fn days_are_24_hours() -> SpanRelativeTo<'static>

Creates a special marker that indicates all days ought to be assumed to be 24 hours without providing a relative reference time.

This is relevant to the following APIs:

Specifically, in a previous version of Jiff, the above APIs permitted silently assuming that days are always 24 hours when a relative reference date wasn't provided. In the current version of Jiff, this silent interpretation no longer happens and instead an error will occur.

If you need to use these APIs with spans that contain non-zero units of days or weeks but without a relative reference date, then you may use this routine to create a special marker for SpanRelativeTo that permits the APIs above to assume days are always 24 hours.

Motivation

The purpose of the marker is two-fold:

  • Requiring the marker is important for improving the consistency of Span APIs. Previously, some APIs (like Timestamp::checked_add) would always return an error if the Span given had non-zero units of days or greater. On the other hand, other APIs (like Span::checked_add) would autoamtically assume days were always 24 hours if no relative reference time was given and either span had non-zero units of days. With this marker, APIs never assume days are always 24 hours automatically.
  • When it is appropriate to assume all days are 24 hours (for example, when only dealing with spans derived from civil datetimes) and where providing a relative reference datetime doesn't make sense. In this case, one could provide a "dummy" reference date since the precise date in civil time doesn't impact the length of a day. But a marker like the one returned here is more explicit for the purpose of assuming days are always 24 hours.

With that said, ideally, callers should provide a relative reference datetime if possible.

See Issue #48 for more discussion on this topic.

Example: different interpretations of "1 day"

This example shows how "1 day" can be interpreted differently via the Span::total API:

use jiff::{SpanRelativeTo, ToSpan, Unit, Zoned};

let span = 1.day();

// An error because days aren't always 24 hours:
assert_eq!(
    span.total(Unit::Hour).unwrap_err().to_string(),
    "using unit 'day' in a span or configuration requires that either \
     a relative reference time be given or \
     `SpanRelativeTo::days_are_24_hours()` is used to indicate \
     invariant 24-hour days, but neither were provided",
);
// Opt into invariant 24 hour days without a relative date:
let marker = SpanRelativeTo::days_are_24_hours();
let hours = span.total((Unit::Hour, marker))?;
assert_eq!(hours, 24.0);
// Days can be shorter than 24 hours:
let zdt: Zoned = "2024-03-10[America/New_York]".parse()?;
let hours = span.total((Unit::Hour, &zdt))?;
assert_eq!(hours, 23.0);
// Days can be longer than 24 hours:
let zdt: Zoned = "2024-11-03[America/New_York]".parse()?;
let hours = span.total((Unit::Hour, &zdt))?;
assert_eq!(hours, 25.0);

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

Similar behavior applies to the other APIs listed above.

Example: different interpretations of "1 week"

This example shows how "1 week" can be interpreted differently via the Span::total API:

use jiff::{SpanRelativeTo, ToSpan, Unit, Zoned};

let span = 1.week();

// An error because days aren't always 24 hours:
assert_eq!(
    span.total(Unit::Hour).unwrap_err().to_string(),
    "using unit 'week' in a span or configuration requires that either \
     a relative reference time be given or \
     `SpanRelativeTo::days_are_24_hours()` is used to indicate \
     invariant 24-hour days, but neither were provided",
);
// Opt into invariant 24 hour days without a relative date:
let marker = SpanRelativeTo::days_are_24_hours();
let hours = span.total((Unit::Hour, marker))?;
assert_eq!(hours, 168.0);
// Weeks can be shorter than 24*7 hours:
let zdt: Zoned = "2024-03-10[America/New_York]".parse()?;
let hours = span.total((Unit::Hour, &zdt))?;
assert_eq!(hours, 167.0);
// Weeks can be longer than 24*7 hours:
let zdt: Zoned = "2024-11-03[America/New_York]".parse()?;
let hours = span.total((Unit::Hour, &zdt))?;
assert_eq!(hours, 169.0);

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

Example: working with civil::Date

A Span returned by computing the difference in time between two civil::Dates will have a non-zero number of days. In older versions of Jiff, if one wanted to add spans returned by these APIs, you could do so without futzing with relative dates. But now you either need to provide a relative date:

use jiff::{civil::date, ToSpan};

let d1 = date(2025, 1, 18);
let d2 = date(2025, 1, 26);
let d3 = date(2025, 2, 14);

let span1 = d2 - d1;
let span2 = d3 - d2;
let total = span1.checked_add((span2, d1))?;
assert_eq!(total, 27.days().fieldwise());

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

Or you can provide a marker indicating that days are always 24 hours. This is fine for this use case since one is only doing civil calendar arithmetic and not working with time zones:

use jiff::{civil::date, SpanRelativeTo, ToSpan};

let d1 = date(2025, 1, 18);
let d2 = date(2025, 1, 26);
let d3 = date(2025, 2, 14);

let span1 = d2 - d1;
let span2 = d3 - d2;
let total = span1.checked_add(
    (span2, SpanRelativeTo::days_are_24_hours()),
)?;
assert_eq!(total, 27.days().fieldwise());

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

impl From for SpanRelativeTo<'static>

fn from(date: Date) -> SpanRelativeTo<'static>

impl From for SpanRelativeTo<'static>

fn from(dt: DateTime) -> SpanRelativeTo<'static>

impl<'a> Clone for SpanRelativeTo<'a>

fn clone(self: &Self) -> SpanRelativeTo<'a>

impl<'a> Copy for SpanRelativeTo<'a>

impl<'a> Debug for SpanRelativeTo<'a>

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

impl<'a> Freeze for SpanRelativeTo<'a>

impl<'a> From for SpanRelativeTo<'a>

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

impl<'a> RefUnwindSafe for SpanRelativeTo<'a>

impl<'a> Send for SpanRelativeTo<'a>

impl<'a> Sync for SpanRelativeTo<'a>

impl<'a> Unpin for SpanRelativeTo<'a>

impl<'a> UnsafeUnpin for SpanRelativeTo<'a>

impl<'a> UnwindSafe for SpanRelativeTo<'a>

impl<T> Any for SpanRelativeTo<'a>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for SpanRelativeTo<'a>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for SpanRelativeTo<'a>

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

impl<T> CloneToUninit for SpanRelativeTo<'a>

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

impl<T> From for SpanRelativeTo<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for SpanRelativeTo<'a>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for SpanRelativeTo<'a>

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for SpanRelativeTo<'a>

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

impl<T, U> TryInto for SpanRelativeTo<'a>

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