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

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

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

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

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:?}",
    );
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Or, consider using Jiff's own SignedDuration instead:

# // See: https://github.com/rust-lang/rust/pull/121364
# #![allow(unknown_lints, ambiguous_negative_literals)]
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));

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