Struct SpanRelativeTo

pub struct SpanRelativeTo<'a> { /* private fields */ }

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:

• Span::round rounds spans. A relative datetime is necessary when dealing with calendar units. (But spans without calendar units can be rounded without providing a relative datetime.)
• Span arithmetic via Span::checked_add and Span::checked_sub. A relative datetime is needed when adding or subtracting spans with calendar units.
• Span comarisons via Span::compare require a relative datetime when comparing spans with calendar units.
• Computing the “total” duration as a single floating point number via Span::total also requires a relative datetime when dealing with calendar units.

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

Implementations

impl<'a> SpanRelativeTo<'a>

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

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

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

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

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

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

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

impl From<Date> for SpanRelativeTo<'static>

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

Converts to this type from the input type.

impl From<DateTime> for SpanRelativeTo<'static>

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

Converts to this type from the input type.

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