Struct SpanRelativeToCopy item path

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:

• Span::checked_add
• Span::checked_sub
• Span::compare
• Span::total
• Span::round
• Span::to_jiff_duration

Specifically, in jiff 0.1, the above APIs permitted silently assuming that days are always 24 hours when a relative reference date wasn’t provided. This functionality has been deprecated, and in jiff 0.2, this will turn into an error.

If you need to use these APIs with spans that contain non-zero units of days but without a relative reference time, 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.

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

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

// In `jiff 0.2`, this will return an error.
let hours = span.total(Unit::Hour)?;
assert_eq!(hours, 24.0);
// In `jiff 0.2`, this will continue to work.
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);

Similar behavior applies to the other APIs listed above.

§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. Previously, if one wanted to add spans returned by these APIs, you could do so without futzing with relative dates:

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;
// This will return an error in `jiff 0.2`:
let total = span1.checked_add(span2)?;
assert_eq!(total, 27.days().fieldwise());

But the above will stop working in jiff 0.2. The arithmetic call will return an error. Instead, you can either 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;
// This will continue to work in `jiff 0.2`:
let total = span1.checked_add((span2, d1))?;
assert_eq!(total, 27.days().fieldwise());

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;
// This will continue to work in `jiff 0.2`:
let total = span1.checked_add(
    (span2, SpanRelativeTo::days_are_24_hours()),
)?;
assert_eq!(total, 27.days().fieldwise());

Returns the argument unchanged.

Calls U::from(self).

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