Struct SpanTotal

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

Expand description

Options for Span::total.

This type provides a way to ergonomically determine the number of a particular unit in a span, with a potentially fractional component, with an optional relative datetime. Namely, a relative datetime is only needed when the span has a non-zero calendar unit (years, months, weeks or days). Otherwise, an error will be returned.

Callers may use SpanTotal::days_are_24_hours to opt into 24-hour invariant days (and 7-day weeks) without providing a relative datetime.

The main way to construct values of this type is with its From trait implementations:

From<Unit> for SpanTotal computes a total for the given unit in the receiver span for Span::total.
From<(Unit, civil::Date)> for SpanTotal computes a total for the given unit in the receiver span for Span::total, relative to the given date. There are also From implementations for civil::DateTime, Zoned and SpanRelativeTo.

§Example

This example shows how to find the number of seconds in a particular span:

use jiff::{ToSpan, Unit};

let span = 3.hours().minutes(10);
assert_eq!(span.total(Unit::Second)?, 11_400.0);

§Example: 24 hour days

This shows how to find the total number of 24 hour days in 123,456,789 seconds.

use jiff::{SpanTotal, ToSpan, Unit};

let span = 123_456_789.seconds();
assert_eq!(
    span.total(SpanTotal::from(Unit::Day).days_are_24_hours())?,
    1428.8980208333332,
);

§Example: DST is taken into account

The month of March 2024 in America/New_York had 31 days, but one of those days was 23 hours long due a transition into daylight saving time:

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

let span = 744.hours();
let relative = date(2024, 3, 1).in_tz("America/New_York")?;
// Because of the short day, 744 hours is actually a little *more* than
// 1 month starting from 2024-03-01.
assert_eq!(span.total((Unit::Month, &relative))?, 1.0013888888888889);

Now compare what happens when the relative datetime is civil and not time zone aware:

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

let span = 744.hours();
let relative = date(2024, 3, 1);
assert_eq!(span.total((Unit::Month, relative))?, 1.0);

Implementations§

§

impl<'a> SpanTotal<'a>

pub fn days_are_24_hours(self) -> SpanTotal<'a>

This is a convenience function for setting the relative option on this configuration to SpanRelativeTo::days_are_24_hours.

§Example

When computing the total duration for spans involving days, either a relative datetime must be provided, or a special assertion opting into 24-hour days is required. Otherwise, you get an error.

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

let span = 2.days().hours(12);

// No relative date provided, which results in an error.
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",
);

// If we can assume all days are 24 hours, then we can assert it:
let total = span.total(
    SpanTotal::from(Unit::Hour).days_are_24_hours(),
)?;
assert_eq!(total, 60.0);

// Or provide a relative datetime, which is preferred if possible:
let total = span.total((Unit::Hour, date(2025, 1, 26)))?;
assert_eq!(total, 60.0);

Trait Implementations§

§

impl<'a> Clone for SpanTotal<'a>

§

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

Returns a duplicate of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

§

impl<'a> Debug for SpanTotal<'a>

§

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

Formats the value using the given formatter. Read more

§