Struct Span

Source

pub struct Span { /* private fields */ }

Expand description

A span of time represented via a mixture of calendar and clock units.

A span represents a duration of time in units of years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds and nanoseconds. Spans are used to as inputs to routines like Zoned::checked_add and Date::saturating_sub, and are also outputs from routines like Timestamp::since and DateTime::until.

§Range of spans

Except for nanoseconds, each unit can represent the full span of time expressible via any combination of datetime supported by Jiff. For example:

use jiff::{civil::{DateTime, DateTimeDifference}, ToSpan, Unit};

let options = DateTimeDifference::new(DateTime::MAX).largest(Unit::Year);
assert_eq!(DateTime::MIN.until(options)?.get_years(), 19_998);

let options = options.largest(Unit::Day);
assert_eq!(DateTime::MIN.until(options)?.get_days(), 7_304_483);

let options = options.largest(Unit::Microsecond);
assert_eq!(
    DateTime::MIN.until(options)?.get_microseconds(),
    631_107_417_599_999_999i64,
);

let options = options.largest(Unit::Nanosecond);
// Span is too big, overflow!
assert!(DateTime::MIN.until(options).is_err());

§Building spans

A default or empty span corresponds to a duration of zero time:

use jiff::Span;

assert!(Span::new().is_zero());
assert!(Span::default().is_zero());

Spans are Copy types that have mutator methods on them for creating new spans:

use jiff::Span;

let span = Span::new().days(5).hours(8).minutes(1);
assert_eq!(span.to_string(), "P5DT8H1M");

But Jiff provides a ToSpan trait that defines extension methods on primitive signed integers to make span creation terser:

use jiff::ToSpan;

let span = 5.days().hours(8).minutes(1);
assert_eq!(span.to_string(), "P5DT8H1M");
// singular units on integers can be used too:
let span = 1.day().hours(8).minutes(1);
assert_eq!(span.to_string(), "P1DT8H1M");

§Negative spans

A span may be negative. All of these are equivalent:

use jiff::{Span, ToSpan};

let span = -Span::new().days(5);
assert_eq!(span.to_string(), "-P5D");

let span = Span::new().days(5).negate();
assert_eq!(span.to_string(), "-P5D");

let span = Span::new().days(-5);
assert_eq!(span.to_string(), "-P5D");

let span = -Span::new().days(-5).negate();
assert_eq!(span.to_string(), "-P5D");

let span = -5.days();
assert_eq!(span.to_string(), "-P5D");

let span = (-5).days();
assert_eq!(span.to_string(), "-P5D");

let span = -(5.days());
assert_eq!(span.to_string(), "-P5D");

The sign of a span applies to the entire span. When a span is negative, then all of its units are negative:

use jiff::ToSpan;

let span = -5.days().hours(10).minutes(1);
assert_eq!(span.get_days(), -5);
assert_eq!(span.get_hours(), -10);
assert_eq!(span.get_minutes(), -1);

And if any of a span’s units are negative, then the entire span is regarded as negative:

use jiff::ToSpan;

// It's the same thing.
let span = (-5).days().hours(-10).minutes(-1);
assert_eq!(span.get_days(), -5);
assert_eq!(span.get_hours(), -10);
assert_eq!(span.get_minutes(), -1);

// Still the same. All negative.
let span = 5.days().hours(-10).minutes(1);
assert_eq!(span.get_days(), -5);
assert_eq!(span.get_hours(), -10);
assert_eq!(span.get_minutes(), -1);

// But this is not! The negation in front applies
// to the entire span, which was already negative
// by virtue of at least one of its units being
// negative. So the negation operator in front turns
// the span positive.
let span = -5.days().hours(-10).minutes(-1);
assert_eq!(span.get_days(), 5);
assert_eq!(span.get_hours(), 10);
assert_eq!(span.get_minutes(), 1);

You can also ask for the absolute value of a span:

use jiff::Span;

let span = Span::new().days(5).hours(10).minutes(1).negate().abs();
assert_eq!(span.get_days(), 5);
assert_eq!(span.get_hours(), 10);
assert_eq!(span.get_minutes(), 1);

§Parsing and printing

The Span type provides convenient trait implementations of std::str::FromStr and std::fmt::Display:

use jiff::{Span, ToSpan};

let span: Span = "P2m10dT2h30m".parse()?;
// By default, capital unit designator labels are used.
// This can be changed with `jiff::fmt::temporal::SpanPrinter::lowercase`.
assert_eq!(span.to_string(), "P2M10DT2H30M");

// Or use the "friendly" format by invoking the `Display` alternate:
assert_eq!(format!("{span:#}"), "2mo 10d 2h 30m");

// Parsing automatically supports both the ISO 8601 and "friendly"
// formats. Note that we use `Span::fieldwise` to create a `Span` that
// compares based on each field. To compare based on total duration, use
// `Span::compare` or `Span::total`.
let span: Span = "2mo 10d 2h 30m".parse()?;
assert_eq!(span, 2.months().days(10).hours(2).minutes(30).fieldwise());
let span: Span = "2 months, 10 days, 2 hours, 30 minutes".parse()?;
assert_eq!(span, 2.months().days(10).hours(2).minutes(30).fieldwise());

The format supported is a variation (nearly a subset) of the duration format specified in ISO 8601 and a Jiff-specific “friendly” format. Here are more examples:

use jiff::{Span, ToSpan};

let spans = [
    // ISO 8601
    ("P40D", 40.days()),
    ("P1y1d", 1.year().days(1)),
    ("P3dT4h59m", 3.days().hours(4).minutes(59)),
    ("PT2H30M", 2.hours().minutes(30)),
    ("P1m", 1.month()),
    ("P1w", 1.week()),
    ("P1w4d", 1.week().days(4)),
    ("PT1m", 1.minute()),
    ("PT0.0021s", 2.milliseconds().microseconds(100)),
    ("PT0s", 0.seconds()),
    ("P0d", 0.seconds()),
    (
        "P1y1m1dT1h1m1.1s",
        1.year().months(1).days(1).hours(1).minutes(1).seconds(1).milliseconds(100),
    ),
    // Jiff's "friendly" format
    ("40d", 40.days()),
    ("40 days", 40.days()),
    ("1y1d", 1.year().days(1)),
    ("1yr 1d", 1.year().days(1)),
    ("3d4h59m", 3.days().hours(4).minutes(59)),
    ("3 days, 4 hours, 59 minutes", 3.days().hours(4).minutes(59)),
    ("3d 4h 59m", 3.days().hours(4).minutes(59)),
    ("2h30m", 2.hours().minutes(30)),
    ("2h 30m", 2.hours().minutes(30)),
    ("1mo", 1.month()),
    ("1w", 1.week()),
    ("1 week", 1.week()),
    ("1w4d", 1.week().days(4)),
    ("1 wk 4 days", 1.week().days(4)),
    ("1m", 1.minute()),
    ("0.0021s", 2.milliseconds().microseconds(100)),
    ("0s", 0.seconds()),
    ("0d", 0.seconds()),
    ("0 days", 0.seconds()),
    (
        "1y1mo1d1h1m1.1s",
        1.year().months(1).days(1).hours(1).minutes(1).seconds(1).milliseconds(100),
    ),
    (
        "1yr 1mo 1day 1hr 1min 1.1sec",
        1.year().months(1).days(1).hours(1).minutes(1).seconds(1).milliseconds(100),
    ),
    (
        "1 year, 1 month, 1 day, 1 hour, 1 minute 1.1 seconds",
        1.year().months(1).days(1).hours(1).minutes(1).seconds(1).milliseconds(100),
    ),
    (
        "1 year, 1 month, 1 day, 01:01:01.1",
        1.year().months(1).days(1).hours(1).minutes(1).seconds(1).milliseconds(100),
    ),
];
for (string, span) in spans {
    let parsed: Span = string.parse()?;
    assert_eq!(
        span.fieldwise(),
        parsed.fieldwise(),
        "result of parsing {string:?}",
    );
}

For more details, see the fmt::temporal and fmt::friendly modules.

§Comparisons

A Span does not implement the PartialEq or Eq traits. These traits were implemented in an earlier version of Jiff, but they made it too easy to introduce bugs. For example, 120.minutes() and 2.hours() always correspond to the same total duration, but they have different representations in memory and so didn’t compare equivalent.

The reason why the PartialEq and Eq trait implementations do not do comparisons with total duration is because it is fundamentally impossible to do such comparisons without a reference date in all cases.

However, it is undeniably occasionally useful to do comparisons based on the component fields, so long as such use cases can tolerate two different spans comparing unequal even when their total durations are equivalent. For example, many of the tests in Jiff (including the tests in the documentation) work by comparing a Span to an expected result. This is a good demonstration of when fieldwise comparisons are appropriate.

To do fieldwise comparisons with a span, use the Span::fieldwise method. This method creates a SpanFieldwise, which is just a Span that implements PartialEq and Eq in a fieldwise manner. In other words, it’s a speed bump to ensure this is the kind of comparison you actually want. For example:

use jiff::ToSpan;

assert_ne!(1.hour().fieldwise(), 60.minutes().fieldwise());
// These also work since you only need one fieldwise span to do a compare:
assert_ne!(1.hour(), 60.minutes().fieldwise());
assert_ne!(1.hour().fieldwise(), 60.minutes());

This is because doing true comparisons requires arithmetic and a relative datetime in the general case, and which can fail due to overflow. This operation is provided via Span::compare:

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

// This doesn't need a reference date since it's only using time units.
assert_eq!(1.hour().compare(60.minutes())?, std::cmp::Ordering::Equal);
// But if you have calendar units, then you need a
// reference date at minimum:
assert!(1.month().compare(30.days()).is_err());
assert_eq!(
    1.month().compare((30.days(), date(2025, 6, 1)))?,
    std::cmp::Ordering::Equal,
);
// A month can be a differing number of days!
assert_eq!(
    1.month().compare((30.days(), date(2025, 7, 1)))?,
    std::cmp::Ordering::Greater,
);

§Arithmetic

Spans can be added or subtracted via Span::checked_add and Span::checked_sub:

use jiff::{Span, ToSpan};

let span1 = 2.hours().minutes(20);
let span2: Span = "PT89400s".parse()?;
assert_eq!(span1.checked_add(span2)?, 27.hours().minutes(10).fieldwise());

When your spans involve calendar units, a relative datetime must be provided. (Because, for example, 1 month from March 1 is 31 days, but 1 month from April 1 is 30 days.)

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

let span1 = 2.years().months(6).days(20);
let span2 = 400.days();
assert_eq!(
    span1.checked_add((span2, date(2023, 1, 1)))?,
    3.years().months(7).days(24).fieldwise(),
);
// The span changes when a leap year isn't included!
assert_eq!(
    span1.checked_add((span2, date(2025, 1, 1)))?,
    3.years().months(7).days(23).fieldwise(),
);

§Rounding and balancing

Unlike datetimes, multiple distinct Span values can actually correspond to the same duration of time. For example, all of the following correspond to the same duration:

2 hours, 30 minutes
150 minutes
1 hour, 90 minutes

The first is said to be balanced. That is, its biggest non-zero unit cannot be expressed in an integer number of units bigger than hours. But the second is unbalanced because 150 minutes can be split up into hours and minutes. We call this sort of span a “top-heavy” unbalanced span. The third span is also unbalanced, but it’s “bottom-heavy” and rarely used. Jiff will generally only produce spans of the first two types. In particular, most Span producing APIs accept a “largest” Unit parameter, and the result can be said to be a span “balanced up to the largest unit provided.”

Balanced and unbalanced spans can be switched between as needed via the Span::round API by providing a rounding configuration with SpanRound::largest` set:

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

let span = 2.hours().minutes(30);
let unbalanced = span.round(SpanRound::new().largest(Unit::Minute))?;
assert_eq!(unbalanced, 150.minutes().fieldwise());
let balanced = unbalanced.round(SpanRound::new().largest(Unit::Hour))?;
assert_eq!(balanced, 2.hours().minutes(30).fieldwise());

Balancing can also be done as part of computing spans from two datetimes:

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

let zdt1 = date(2024, 7, 7).at(15, 23, 0, 0).in_tz("America/New_York")?;
let zdt2 = date(2024, 11, 5).at(8, 0, 0, 0).in_tz("America/New_York")?;

// To make arithmetic reversible, the default largest unit for spans of
// time computed from zoned datetimes is hours:
assert_eq!(zdt1.until(&zdt2)?, 2_897.hour().minutes(37).fieldwise());
// But we can ask for the span to be balanced up to years:
assert_eq!(
    zdt1.until((Unit::Year, &zdt2))?,
    3.months().days(28).hours(16).minutes(37).fieldwise(),
);

While the Span::round API does balancing, it also, of course, does rounding as well. Rounding occurs when the smallest unit is set to something bigger than Unit::Nanosecond:

use jiff::{ToSpan, Unit};

let span = 2.hours().minutes(30);
assert_eq!(span.round(Unit::Hour)?, 3.hours().fieldwise());

When rounding spans with calendar units (years, months or weeks), then a relative datetime is required:

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

let span = 10.years().months(11);
let options = SpanRound::new()
    .smallest(Unit::Year)
    .relative(date(2024, 1, 1));
assert_eq!(span.round(options)?, 11.years().fieldwise());

§Days are not always 24 hours!

That is, a Span is made up of uniform and non-uniform units.

A uniform unit is a unit whose elapsed duration is always the same. A non-uniform unit is a unit whose elapsed duration is not always the same. There are two things that can impact the length of a non-uniform unit: the calendar date and the time zone.

Years and months are always considered non-uniform units. For example, 1 month from 2024-04-01 is 30 days, while 1 month from 2024-05-01 is 31 days. Similarly for years because of leap years.

Hours, minutes, seconds, milliseconds, microseconds and nanoseconds are always considered uniform units.

Days are only considered non-uniform when in the presence of a zone aware datetime. A day can be more or less than 24 hours, and it can be balanced up and down, but only when a relative zoned datetime is given. This typically happens because of DST (daylight saving time), but can also occur because of other time zone transitions too.

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

// 2024-03-10 in New York was 23 hours long,
// because of a jump to DST at 2am.
let zdt = date(2024, 3, 9).at(21, 0, 0, 0).in_tz("America/New_York")?;
// Goes from days to hours:
assert_eq!(
    1.day().round(SpanRound::new().largest(Unit::Hour).relative(&zdt))?,
    23.hours().fieldwise(),
);
// Goes from hours to days:
assert_eq!(
    23.hours().round(SpanRound::new().largest(Unit::Day).relative(&zdt))?,
    1.day().fieldwise(),
);
// 24 hours is more than 1 day starting at this time:
assert_eq!(
    24.hours().round(SpanRound::new().largest(Unit::Day).relative(&zdt))?,
    1.day().hours(1).fieldwise(),
);

And similarly, days can be longer than 24 hours:

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

// 2024-11-03 in New York was 25 hours long,
// because of a repetition of the 1 o'clock AM hour.
let zdt = date(2024, 11, 2).at(21, 0, 0, 0).in_tz("America/New_York")?;
// Goes from days to hours:
assert_eq!(
    1.day().round(SpanRound::new().largest(Unit::Hour).relative(&zdt))?,
    25.hours().fieldwise(),
);
// Goes from hours to days:
assert_eq!(
    25.hours().round(SpanRound::new().largest(Unit::Day).relative(&zdt))?,
    1.day().fieldwise(),
);
// 24 hours is less than 1 day starting at this time,
// so it stays in units of hours even though we ask
// for days (because 24 isn't enough hours to make
// 1 day):
assert_eq!(
    24.hours().round(SpanRound::new().largest(Unit::Day).relative(&zdt))?,
    24.hours().fieldwise(),
);

The APIs on Span will otherwise treat days as non-uniform unless a relative civil date is given, or there is an explicit opt-in to invariant 24-hour days. For example:

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

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))?;
// Or use a relative civil date, and all days are 24 hours:
let date = civil::date(2020, 1, 1);
let hours = span.total((Unit::Hour, date))?;
assert_eq!(hours, 24.0);

In Jiff, all weeks are 7 days. And generally speaking, weeks only appear in a Span if they were explicitly put there by the caller or if they were explicitly requested by the caller in an API. For example:

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

let dt1 = date(2024, 1, 1).at(0, 0, 0, 0);
let dt2 = date(2024, 7, 16).at(0, 0, 0, 0);
// Default units go up to days.
assert_eq!(dt1.until(dt2)?, 197.days().fieldwise());
// No weeks, even though we requested up to year.
assert_eq!(dt1.until((Unit::Year, dt2))?, 6.months().days(15).fieldwise());
// We get weeks only when we ask for them.
assert_eq!(dt1.until((Unit::Week, dt2))?, 28.weeks().days(1).fieldwise());

§Integration with `std::time::Duration` and `SignedDuration`

While Jiff primarily uses a Span for doing arithmetic on datetimes, one can convert between a Span and a std::time::Duration or a SignedDuration. The main difference between them is that a Span always keeps tracks of its individual units, and a Span can represent non-uniform units like months. In contrast, Duration and SignedDuration are always an exact elapsed amount of time. They don’t distinguish between 120 seconds and 2 minutes. And they can’t represent the concept of “months” because a month doesn’t have a single fixed amount of time.

However, an exact duration is still useful in certain contexts. Beyond that, it serves as an interoperability point due to the presence of an unsigned exact duration type in the standard library. Because of that, Jiff provides TryFrom trait implementations for converting to and from a std::time::Duration (and, of course, a SignedDuration). For example, to convert from a std::time::Duration to a Span:

use std::time::Duration;

use jiff::{Span, ToSpan};

let duration = Duration::new(86_400, 123_456_789);
let span = Span::try_from(duration)?;
// A duration-to-span conversion always results in a span with
// non-zero units no bigger than seconds.
assert_eq!(
    span.fieldwise(),
    86_400.seconds().milliseconds(123).microseconds(456).nanoseconds(789),
);

// Note that the conversion is fallible! For example:
assert!(Span::try_from(Duration::from_secs(u64::MAX)).is_err());
// At present, a Jiff `Span` can only represent a range of time equal to
// the range of time expressible via minimum and maximum Jiff timestamps.
// Which is roughly -9999-01-01 to 9999-12-31, or ~20,000 years.
assert!(Span::try_from(Duration::from_secs(999_999_999_999)).is_err());

And to convert from a Span to a std::time::Duration:

use std::time::Duration;

use jiff::{Span, ToSpan};

let span = 86_400.seconds()
    .milliseconds(123)
    .microseconds(456)
    .nanoseconds(789);
let duration = Duration::try_from(span)?;
assert_eq!(duration, Duration::new(86_400, 123_456_789));

Note that an error will occur when converting a Span to a std::time::Duration using the TryFrom trait implementation with units bigger than hours:

use std::time::Duration;

use jiff::ToSpan;

let span = 2.days().hours(10);
assert_eq!(
    Duration::try_from(span).unwrap_err().to_string(),
    "failed to convert span to duration without relative datetime \
     (must use `Span::to_duration` instead): 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",
);

Similar code can be written for SignedDuration as well.

If you need to convert such spans, then as the error suggests, you’ll need to use Span::to_duration with a relative date.

And note that since a Span is signed and a std::time::Duration is unsigned, converting a negative Span to std::time::Duration will always fail. One can use Span::signum to get the sign of the span and Span::abs to make the span positive before converting it to a Duration:

use std::time::Duration;

use jiff::{Span, ToSpan};

let span = -86_400.seconds().nanoseconds(1);
let (sign, duration) = (span.signum(), Duration::try_from(span.abs())?);
assert_eq!((sign, duration), (-1, Duration::new(86_400, 1)));

Or, consider using Jiff’s own SignedDuration instead:

use jiff::{SignedDuration, Span, ToSpan};

let span = -86_400.seconds().nanoseconds(1);
let duration = SignedDuration::try_from(span)?;
assert_eq!(duration, SignedDuration::new(-86_400, -1));

Struct SpanCopy item path

§Range of spans

§Building spans

§Negative spans

§Parsing and printing

§Comparisons

§Arithmetic

§Rounding and balancing

§Days are not always 24 hours!

§Integration with std::time::Duration and SignedDuration

Implementations§

impl Span

pub fn new() -> Span

pub fn years<I>(self, years: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn months<I>(self, months: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn weeks<I>(self, weeks: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn days<I>(self, days: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn hours<I>(self, hours: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn minutes<I>(self, minutes: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn seconds<I>(self, seconds: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn milliseconds<I>(self, milliseconds: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn microseconds<I>(self, microseconds: I) -> Spanwhere I: Into<i64>,

§Panics

pub fn nanoseconds<I>(self, nanoseconds: I) -> Spanwhere I: Into<i64>,

§Panics

impl Span

pub fn try_years<I>(self, years: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_months<I>(self, months: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_weeks<I>(self, weeks: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_days<I>(self, days: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_hours<I>(self, hours: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_minutes<I>(self, minutes: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_seconds<I>(self, seconds: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_milliseconds<I>(self, milliseconds: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_microseconds<I>(self, microseconds: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

pub fn try_nanoseconds<I>(self, nanoseconds: I) -> Result<Span, Error>where I: Into<i64>,

§Errors

impl Span

pub fn get_years(&self) -> i16

§Example

pub fn get_months(&self) -> i32

§Example

pub fn get_weeks(&self) -> i32

§Example

pub fn get_days(&self) -> i32

§Example

pub fn get_hours(&self) -> i32

§Example

pub fn get_minutes(&self) -> i64

§Example

pub fn get_seconds(&self) -> i64

§Example

pub fn get_milliseconds(&self) -> i64

§Example

pub fn get_microseconds(&self) -> i64

§Example

pub fn get_nanoseconds(&self) -> i64

§Example

impl Span

pub fn abs(self) -> Span

§Example

pub fn negate(self) -> Span

§Example

Struct Span

§Integration with `std::time::Duration` and `SignedDuration`

pub fn years<I>(self, years: I) -> Span
where I: Into<i64>,

pub fn months<I>(self, months: I) -> Span
where I: Into<i64>,

pub fn weeks<I>(self, weeks: I) -> Span
where I: Into<i64>,

pub fn days<I>(self, days: I) -> Span
where I: Into<i64>,

pub fn hours<I>(self, hours: I) -> Span
where I: Into<i64>,

pub fn minutes<I>(self, minutes: I) -> Span
where I: Into<i64>,

pub fn seconds<I>(self, seconds: I) -> Span
where I: Into<i64>,

pub fn milliseconds<I>(self, milliseconds: I) -> Span
where I: Into<i64>,

pub fn microseconds<I>(self, microseconds: I) -> Span
where I: Into<i64>,

pub fn nanoseconds<I>(self, nanoseconds: I) -> Span
where I: Into<i64>,

pub fn try_years<I>(self, years: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_months<I>(self, months: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_weeks<I>(self, weeks: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_days<I>(self, days: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_hours<I>(self, hours: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_minutes<I>(self, minutes: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_seconds<I>(self, seconds: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_milliseconds<I>(self, milliseconds: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_microseconds<I>(self, microseconds: I) -> Result<Span, Error>
where I: Into<i64>,

pub fn try_nanoseconds<I>(self, nanoseconds: I) -> Result<Span, Error>
where I: Into<i64>,

§Example: the difference between `SpanFieldwise` and `Span::compare`

pub fn checked_add<'a, A>(&self, options: A) -> Result<Span, Error>
where A: Into<SpanArithmetic<'a>>,

pub fn checked_sub<'a, A>(&self, options: A) -> Result<Span, Error>
where A: Into<SpanArithmetic<'a>>,

pub fn compare<'a, C>(&self, options: C) -> Result<Ordering, Error>
where C: Into<SpanCompare<'a>>,

pub fn total<'a, T>(&self, options: T) -> Result<f64, Error>
where T: Into<SpanTotal<'a>>,

pub fn round<'a, R>(self, options: R) -> Result<Span, Error>
where R: Into<SpanRound<'a>>,

§Constructing a `SpanRound`

pub fn to_duration<'a, R>(&self, relative: R) -> Result<SignedDuration, Error>
where R: Into<SpanRelativeTo<'a>>,

§Example: converting a span with calendar units to a `SignedDuration`