Struct SpanTotal

struct SpanTotal<'a> { ... }

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:

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

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

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

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

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

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

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

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

Implementations

impl<'a> SpanTotal<'a>

fn days_are_24_hours(self: 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);

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

impl From for SpanTotal<'static>

fn from(unit: Unit) -> SpanTotal<'static>

impl From for SpanTotal<'static>

fn from((unit, date): (Unit, Date)) -> SpanTotal<'static>

impl From for SpanTotal<'static>

fn from((unit, datetime): (Unit, DateTime)) -> SpanTotal<'static>

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

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

impl<'a> Copy for SpanTotal<'a>

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

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

impl<'a> Freeze for SpanTotal<'a>

impl<'a> From for SpanTotal<'a>

fn from((unit, relative): (Unit, SpanRelativeTo<'a>)) -> SpanTotal<'a>

impl<'a> From for SpanTotal<'a>

fn from((unit, zoned): (Unit, &'a Zoned)) -> SpanTotal<'a>

impl<'a> RefUnwindSafe for SpanTotal<'a>

impl<'a> Send for SpanTotal<'a>

impl<'a> Sync for SpanTotal<'a>

impl<'a> Unpin for SpanTotal<'a>

impl<'a> UnsafeUnpin for SpanTotal<'a>

impl<'a> UnwindSafe for SpanTotal<'a>

impl<T> Any for SpanTotal<'a>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for SpanTotal<'a>

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

impl<T> BorrowMut for SpanTotal<'a>

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

impl<T> CloneToUninit for SpanTotal<'a>

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

impl<T> From for SpanTotal<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for SpanTotal<'a>

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

impl<T, U> Into for SpanTotal<'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 SpanTotal<'a>

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

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

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