Struct SpanRelativeTo

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

Available on crate features dep_jiff and alloc only.

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

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

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>