Struct SignedDuration

pub struct SignedDuration { /* private fields */ }

Available on crate features dep_jiff and alloc only.

A signed duration of time represented as a 96-bit integer of nanoseconds.

Each duration is made up of a 64-bit integer of whole seconds and a 32-bit integer of fractional nanoseconds less than 1 whole second. Unlike std::time::Duration, this duration is signed. The sign applies to the entire duration. That is, either both the seconds and the fractional nanoseconds are negative or neither are. Stated differently, it is guaranteed that the signs of SignedDuration::as_secs and SignedDuration::subsec_nanos are always the same.

Parsing and printing

Like the Span type, the SignedDuration type provides convenient trait implementations of std::str::FromStr and std::fmt::Display:

use jiff::SignedDuration;

let duration: SignedDuration = "PT2h30m".parse()?;
assert_eq!(duration.to_string(), "PT2H30M");

// Or use the "friendly" format by invoking the alternate:
assert_eq!(format!("{duration:#}"), "2h 30m");

// Parsing automatically supports both the ISO 8601 and "friendly" formats:
let duration: SignedDuration = "2h 30m".parse()?;
assert_eq!(duration, SignedDuration::new(2 * 60 * 60 + 30 * 60, 0));
let duration: SignedDuration = "2 hours, 30 minutes".parse()?;
assert_eq!(duration, SignedDuration::new(2 * 60 * 60 + 30 * 60, 0));

Unlike the Span type, though, only uniform units are supported. This means that ISO 8601 durations with non-zero units of days or greater cannot be parsed directly into a SignedDuration:

use jiff::SignedDuration;

assert_eq!(
    "P1d".parse::<SignedDuration>().unwrap_err().to_string(),
    "failed to parse ISO 8601 duration string into `SignedDuration`: \
     parsing ISO 8601 duration into SignedDuration requires that the \
     duration contain a time component and no components of days or \
     greater",
);

To parse such durations, one should first parse them into a Span and then convert them to a SignedDuration by providing a relative date:

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

let span: Span = "P1d".parse()?;
let relative = date(2024, 11, 3).intz("US/Eastern")?;
let duration = span.to_jiff_duration(&relative)?;
// This example also motivates *why* a relative date
// is required. Not all days are the same length!
assert_eq!(duration.to_string(), "PT25H");

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::SignedDuration;

let durations = [
    // ISO 8601
    ("PT2H30M", SignedDuration::from_secs(2 * 60 * 60 + 30 * 60)),
    ("PT2.5h", SignedDuration::from_secs(2 * 60 * 60 + 30 * 60)),
    ("PT1m", SignedDuration::from_mins(1)),
    ("PT1.5m", SignedDuration::from_secs(90)),
    ("PT0.0021s", SignedDuration::new(0, 2_100_000)),
    ("PT0s", SignedDuration::ZERO),
    ("PT0.000000001s", SignedDuration::from_nanos(1)),
    // Jiff's "friendly" format
    ("2h30m", SignedDuration::from_secs(2 * 60 * 60 + 30 * 60)),
    ("2 hrs 30 mins", SignedDuration::from_secs(2 * 60 * 60 + 30 * 60)),
    ("2 hours 30 minutes", SignedDuration::from_secs(2 * 60 * 60 + 30 * 60)),
    ("2.5h", SignedDuration::from_secs(2 * 60 * 60 + 30 * 60)),
    ("1m", SignedDuration::from_mins(1)),
    ("1.5m", SignedDuration::from_secs(90)),
    ("0.0021s", SignedDuration::new(0, 2_100_000)),
    ("0s", SignedDuration::ZERO),
    ("0.000000001s", SignedDuration::from_nanos(1)),
];
for (string, duration) in durations {
    let parsed: SignedDuration = string.parse()?;
    assert_eq!(duration, parsed, "result of parsing {string:?}");
}

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

API design

A SignedDuration is, as much as is possible, a replica of the std::time::Duration API. While there are probably some quirks in the API of std::time::Duration that could have been fixed here, it is probably more important that it behave “exactly like a std::time::Duration but with a sign.” That is, this type mirrors the parallels between signed and unsigned integer types.

While the goal was to match the std::time::Duration API as much as possible, there are some differences worth highlighting:

• As stated, a SignedDuration has a sign. Therefore, it uses i64 and i32 instead of u64 and u32 to represent its 96-bit integer.
• Because it’s signed, the range of possible values is different. For example, a SignedDuration::MAX has a whole number of seconds equivalent to i64::MAX, which is less than u64::MAX.
• There are some additional APIs that don’t make sense on an unsigned duration, like SignedDuration::abs and SignedDuration::checked_neg.
• A SignedDuration::system_until routine is provided as a replacement for std::time::SystemTime::duration_since, but with signed durations.
• Constructors and getters for units of hours and minutes are provided, where as these routines are unstable in the standard library.
• Unlike the standard library, this type implements the std::fmt::Display and std::str::FromStr traits via the ISO 8601 duration format, just like the Span type does. Also like Span, the ISO 8601 duration format is used to implement the serde Serialize and Deserialize traits when the serde crate feature is enabled.
• The std::fmt::Debug trait implementation is a bit different. If you have a problem with it, please file an issue.
• At present, there is no SignedDuration::abs_diff since there are some API design questions. If you want it, please file an issue.

When should I use SignedDuration versus Span?

Jiff’s primary duration type is Span. The key differences between it and SignedDuration are:

• A Span keeps track of each individual unit separately. That is, even though 1 hour 60 minutes and 2 hours are equivalent durations of time, representing each as a Span corresponds to two distinct values in memory. And serializing them to the ISO 8601 duration format will also preserve the units, for example, PT1h60m and PT2h.
• A Span supports non-uniform units like days, weeks, months and years. Since not all days, weeks, months and years have the same length, they cannot be represented by a SignedDuration. In some cases, it may be appropriate, for example, to assume that all days are 24 hours long. But since Jiff sometimes assumes all days are 24 hours (for civil time) and sometimes doesn’t (like for Zoned when respecting time zones), it would be inappropriate to bake one of those assumptions into a SignedDuration.
• A SignedDuration is a much smaller type than a Span. Specifically, it’s a 96-bit integer. In contrast, a Span is much larger since it needs to track each individual unit separately.

Those differences in turn motivate some approximate reasoning for when to use Span and when to use SignedDuration:

• If you don’t care about keeping track of individual units separately or don’t need the sophisticated rounding options available on a Span, it might be simpler and faster to use a SignedDuration.
• If you specifically need performance on arithmetic operations involving datetimes and durations, even if it’s not as convenient or correct, then it might make sense to use a SignedDuration.
• If you need to perform arithmetic using a std::time::Duration and otherwise don’t need the functionality of a Span, it might make sense to first convert the std::time::Duration to a SignedDuration, and then use one of the corresponding operations defined for SignedDuration on the datetime types. (They all support it.)

In general, a Span provides more functionality and is overall more flexible. A Span can also deserialize all forms of ISO 8601 durations (as long as they’re within Jiff’s limits), including durations with units of years, months, weeks and days. A SignedDuration, by contrast, only supports units up to and including hours.

Integration with datetime types

All datetime types that support arithmetic using Span also support arithmetic using SignedDuration (and std::time::Duration). For example, here’s how to add an absolute duration to a Timestamp:

use jiff::{SignedDuration, Timestamp};

let ts1 = Timestamp::from_second(1_123_456_789)?;
assert_eq!(ts1.to_string(), "2005-08-07T23:19:49Z");

let duration = SignedDuration::new(59, 999_999_999);
// Timestamp::checked_add is polymorphic! It can accept a
// span or a duration.
let ts2 = ts1.checked_add(duration)?;
assert_eq!(ts2.to_string(), "2005-08-07T23:20:48.999999999Z");

The same API pattern works with Zoned, DateTime, Date and Time.

Interaction with daylight saving time and time zone transitions

A SignedDuration always corresponds to a specific number of nanoseconds. Since a Zoned is always a precise instant in time, adding a SignedDuration to a Zoned always behaves by adding the nanoseconds from the duration to the timestamp inside of Zoned. Consider 2024-03-10 in US/Eastern. At 02:00:00, daylight saving time came into effect, switching the UTC offset for the region from -05 to -04. This has the effect of skipping an hour on the clocks:

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

let zdt = date(2024, 3, 10).at(1, 59, 0, 0).intz("US/Eastern")?;
assert_eq!(
    zdt.checked_add(SignedDuration::from_hours(1))?,
    // Time on the clock skipped an hour, but in this time
    // zone, 03:59 is actually precisely 1 hour later than
    // 01:59.
    date(2024, 3, 10).at(3, 59, 0, 0).intz("US/Eastern")?,
);
// The same would apply if you used a `Span`:
assert_eq!(
    zdt.checked_add(jiff::Span::new().hours(1))?,
    // Time on the clock skipped an hour, but in this time
    // zone, 03:59 is actually precisely 1 hour later than
    // 01:59.
    date(2024, 3, 10).at(3, 59, 0, 0).intz("US/Eastern")?,
);

Where time zones might have a more interesting effect is in the definition of the “day” itself. If, for example, you encode the notion that a day is always 24 hours into your arithmetic, you might get unexpected results. For example, let’s say you want to find the datetime precisely one week after 2024-03-08T17:00 in the US/Eastern time zone. You might be tempted to just ask for the time that is 7 * 24 hours later:

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

let zdt = date(2024, 3, 8).at(17, 0, 0, 0).intz("US/Eastern")?;
assert_eq!(
    zdt.checked_add(SignedDuration::from_hours(7 * 24))?,
    date(2024, 3, 15).at(18, 0, 0, 0).intz("US/Eastern")?,
);

Notice that you get 18:00 and not 17:00! That’s because, as shown in the previous example, 2024-03-10 was only 23 hours long. That in turn implies that the week starting from 2024-03-08 is only 7 * 24 - 1 hours long. This can be tricky to get correct with absolute durations like SignedDuration, but a Span will handle this for you automatically:

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

let zdt = date(2024, 3, 8).at(17, 0, 0, 0).intz("US/Eastern")?;
assert_eq!(
    zdt.checked_add(1.week())?,
    // The expected time!
    date(2024, 3, 15).at(17, 0, 0, 0).intz("US/Eastern")?,
);

A Span achieves this by keeping track of individual units. Unlike a SignedDuration, it is not just a simple count of nanoseconds. It is a “bag” of individual units, and the arithmetic operations defined on a Span for Zoned know how to interpret “day” in a particular time zone at a particular instant in time.

With that said, the above does not mean that using a SignedDuration is always wrong. For example, if you’re dealing with units of hours or lower, then all such units are uniform and so you’ll always get the same results as with a Span. And using a SignedDuration can sometimes be simpler or faster.

Implementations

impl SignedDuration

pub const ZERO: SignedDuration

A duration of zero time.

Example

use jiff::SignedDuration;

let duration = SignedDuration::ZERO;
assert!(duration.is_zero());
assert_eq!(duration.as_secs(), 0);
assert_eq!(duration.subsec_nanos(), 0);

pub const MIN: SignedDuration

The minimum possible duration. Or the “most negative” duration.

Example

use jiff::SignedDuration;

let duration = SignedDuration::MIN;
assert_eq!(duration.as_secs(), i64::MIN);
assert_eq!(duration.subsec_nanos(), -999_999_999);

pub const MAX: SignedDuration

The maximum possible duration.

Example

use jiff::SignedDuration;

let duration = SignedDuration::MAX;
assert_eq!(duration.as_secs(), i64::MAX);
assert_eq!(duration.subsec_nanos(), 999_999_999);

pub const fn new(secs: i64, nanos: i32) -> SignedDuration

Creates a new SignedDuration from the given number of whole seconds and additional nanoseconds.

If the absolute value of the nanoseconds is greater than or equal to 1 second, then the excess balances into the number of whole seconds.

Panics

When the absolute value of the nanoseconds is greater than or equal to 1 second and the excess that carries over to the number of whole seconds overflows i64.

This never panics when nanos is less than 1_000_000_000.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 0);
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 0);

let duration = SignedDuration::new(12, -1);
assert_eq!(duration.as_secs(), 11);
assert_eq!(duration.subsec_nanos(), 999_999_999);

let duration = SignedDuration::new(12, 1_000_000_000);
assert_eq!(duration.as_secs(), 13);
assert_eq!(duration.subsec_nanos(), 0);

pub const fn from_secs(secs: i64) -> SignedDuration

Creates a new SignedDuration from the given number of whole seconds.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_secs(12);
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 0);

pub const fn from_millis(millis: i64) -> SignedDuration

Creates a new SignedDuration from the given number of whole milliseconds.

Note that since this accepts an i64, this method cannot be used to construct the full range of possible signed duration values. In particular, SignedDuration::as_millis returns an i128, and this may be a value that would otherwise overflow an i64.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_millis(12_456);
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 456_000_000);

let duration = SignedDuration::from_millis(-12_456);
assert_eq!(duration.as_secs(), -12);
assert_eq!(duration.subsec_nanos(), -456_000_000);

pub const fn from_micros(micros: i64) -> SignedDuration

Creates a new SignedDuration from the given number of whole microseconds.

Note that since this accepts an i64, this method cannot be used to construct the full range of possible signed duration values. In particular, SignedDuration::as_micros returns an i128, and this may be a value that would otherwise overflow an i64.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_micros(12_000_456);
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 456_000);

let duration = SignedDuration::from_micros(-12_000_456);
assert_eq!(duration.as_secs(), -12);
assert_eq!(duration.subsec_nanos(), -456_000);

pub const fn from_nanos(nanos: i64) -> SignedDuration

Creates a new SignedDuration from the given number of whole nanoseconds.

Note that since this accepts an i64, this method cannot be used to construct the full range of possible signed duration values. In particular, SignedDuration::as_nanos returns an i128, which may be a value that would otherwise overflow an i64.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_nanos(12_000_000_456);
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 456);

let duration = SignedDuration::from_nanos(-12_000_000_456);
assert_eq!(duration.as_secs(), -12);
assert_eq!(duration.subsec_nanos(), -456);

pub const fn from_hours(hours: i64) -> SignedDuration

Creates a new SignedDuration from the given number of hours. Every hour is exactly 3,600 seconds.

Panics

Panics if the number of hours, after being converted to nanoseconds, overflows the minimum or maximum SignedDuration values.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_hours(24);
assert_eq!(duration.as_secs(), 86_400);
assert_eq!(duration.subsec_nanos(), 0);

let duration = SignedDuration::from_hours(-24);
assert_eq!(duration.as_secs(), -86_400);
assert_eq!(duration.subsec_nanos(), 0);

pub const fn from_mins(minutes: i64) -> SignedDuration

Creates a new SignedDuration from the given number of minutes. Every minute is exactly 60 seconds.

Panics

Panics if the number of minutes, after being converted to nanoseconds, overflows the minimum or maximum SignedDuration values.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_mins(1_440);
assert_eq!(duration.as_secs(), 86_400);
assert_eq!(duration.subsec_nanos(), 0);

let duration = SignedDuration::from_mins(-1_440);
assert_eq!(duration.as_secs(), -86_400);
assert_eq!(duration.subsec_nanos(), 0);

pub const fn is_zero(&self) -> bool

Returns true if this duration spans no time.

Example

use jiff::SignedDuration;

assert!(SignedDuration::ZERO.is_zero());
assert!(!SignedDuration::MIN.is_zero());
assert!(!SignedDuration::MAX.is_zero());

pub const fn as_secs(&self) -> i64

Returns the number of whole seconds in this duration.

The value returned is negative when the duration is negative.

This does not include any fractional component corresponding to units less than a second. To access those, use one of the subsec methods such as SignedDuration::subsec_nanos.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 999_999_999);
assert_eq!(duration.as_secs(), 12);

let duration = SignedDuration::new(-12, -999_999_999);
assert_eq!(duration.as_secs(), -12);

pub const fn subsec_millis(&self) -> i32

Returns the fractional part of this duration in whole milliseconds.

The value returned is negative when the duration is negative. It is guaranteed that the range of the value returned is in the inclusive range -999..=999.

To get the length of the total duration represented in milliseconds, use SignedDuration::as_millis.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.subsec_millis(), 123);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.subsec_millis(), -123);

pub const fn subsec_micros(&self) -> i32

Returns the fractional part of this duration in whole microseconds.

The value returned is negative when the duration is negative. It is guaranteed that the range of the value returned is in the inclusive range -999_999..=999_999.

To get the length of the total duration represented in microseconds, use SignedDuration::as_micros.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.subsec_micros(), 123_456);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.subsec_micros(), -123_456);

pub const fn subsec_nanos(&self) -> i32

Returns the fractional part of this duration in whole nanoseconds.

The value returned is negative when the duration is negative. It is guaranteed that the range of the value returned is in the inclusive range -999_999_999..=999_999_999.

To get the length of the total duration represented in nanoseconds, use SignedDuration::as_nanos.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.subsec_nanos(), 123_456_789);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.subsec_nanos(), -123_456_789);

pub const fn as_millis(&self) -> i128

Returns the total duration in units of whole milliseconds.

The value returned is negative when the duration is negative.

To get only the fractional component of this duration in units of whole milliseconds, use SignedDuration::subsec_millis.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.as_millis(), 12_123);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.as_millis(), -12_123);

pub const fn as_micros(&self) -> i128

Returns the total duration in units of whole microseconds.

The value returned is negative when the duration is negative.

To get only the fractional component of this duration in units of whole microseconds, use SignedDuration::subsec_micros.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.as_micros(), 12_123_456);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.as_micros(), -12_123_456);

pub const fn as_nanos(&self) -> i128

Returns the total duration in units of whole nanoseconds.

The value returned is negative when the duration is negative.

To get only the fractional component of this duration in units of whole nanoseconds, use SignedDuration::subsec_nanos.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.as_nanos(), 12_123_456_789);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.as_nanos(), -12_123_456_789);

pub const fn checked_add(self, rhs: SignedDuration) -> Option<SignedDuration>

Add two signed durations together. If overflow occurs, then None is returned.

Example

use jiff::SignedDuration;

let duration1 = SignedDuration::new(12, 500_000_000);
let duration2 = SignedDuration::new(0, 500_000_000);
assert_eq!(
    duration1.checked_add(duration2),
    Some(SignedDuration::new(13, 0)),
);

let duration1 = SignedDuration::MAX;
let duration2 = SignedDuration::new(0, 1);
assert_eq!(duration1.checked_add(duration2), None);

pub const fn saturating_add(self, rhs: SignedDuration) -> SignedDuration

Add two signed durations together. If overflow occurs, then arithmetic saturates.

Example

use jiff::SignedDuration;

let duration1 = SignedDuration::MAX;
let duration2 = SignedDuration::new(0, 1);
assert_eq!(duration1.saturating_add(duration2), SignedDuration::MAX);

let duration1 = SignedDuration::MIN;
let duration2 = SignedDuration::new(0, -1);
assert_eq!(duration1.saturating_add(duration2), SignedDuration::MIN);

pub const fn checked_sub(self, rhs: SignedDuration) -> Option<SignedDuration>

Subtract one signed duration from another. If overflow occurs, then None is returned.

Example

use jiff::SignedDuration;

let duration1 = SignedDuration::new(12, 500_000_000);
let duration2 = SignedDuration::new(0, 500_000_000);
assert_eq!(
    duration1.checked_sub(duration2),
    Some(SignedDuration::new(12, 0)),
);

let duration1 = SignedDuration::MIN;
let duration2 = SignedDuration::new(0, 1);
assert_eq!(duration1.checked_sub(duration2), None);

pub const fn saturating_sub(self, rhs: SignedDuration) -> SignedDuration

Add two signed durations together. If overflow occurs, then arithmetic saturates.

Example

use jiff::SignedDuration;

let duration1 = SignedDuration::MAX;
let duration2 = SignedDuration::new(0, -1);
assert_eq!(duration1.saturating_sub(duration2), SignedDuration::MAX);

let duration1 = SignedDuration::MIN;
let duration2 = SignedDuration::new(0, 1);
assert_eq!(duration1.saturating_sub(duration2), SignedDuration::MIN);

pub const fn checked_mul(self, rhs: i32) -> Option<SignedDuration>

Multiply this signed duration by an integer. If the multiplication overflows, then None is returned.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 500_000_000);
assert_eq!(
    duration.checked_mul(2),
    Some(SignedDuration::new(25, 0)),
);

pub const fn saturating_mul(self, rhs: i32) -> SignedDuration

Multiply this signed duration by an integer. If the multiplication overflows, then the result saturates to either the minimum or maximum duration depending on the sign of the product.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(i64::MAX, 0);
assert_eq!(duration.saturating_mul(2), SignedDuration::MAX);
assert_eq!(duration.saturating_mul(-2), SignedDuration::MIN);

let duration = SignedDuration::new(i64::MIN, 0);
assert_eq!(duration.saturating_mul(2), SignedDuration::MIN);
assert_eq!(duration.saturating_mul(-2), SignedDuration::MAX);

pub const fn checked_div(self, rhs: i32) -> Option<SignedDuration>

Divide this duration by an integer. If the division overflows, then None is returned.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 500_000_000);
assert_eq!(
    duration.checked_div(2),
    Some(SignedDuration::new(6, 250_000_000)),
);
assert_eq!(
    duration.checked_div(-2),
    Some(SignedDuration::new(-6, -250_000_000)),
);

let duration = SignedDuration::new(-12, -500_000_000);
assert_eq!(
    duration.checked_div(2),
    Some(SignedDuration::new(-6, -250_000_000)),
);
assert_eq!(
    duration.checked_div(-2),
    Some(SignedDuration::new(6, 250_000_000)),
);

pub fn as_secs_f64(&self) -> f64

Returns the number of seconds, with a possible fractional nanosecond component, represented by this signed duration as a 64-bit float.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.as_secs_f64(), 12.123456789);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.as_secs_f64(), -12.123456789);

pub fn as_secs_f32(&self) -> f32

Returns the number of seconds, with a possible fractional nanosecond component, represented by this signed duration as a 32-bit float.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.as_secs_f32(), 12.123456789);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.as_secs_f32(), -12.123456789);

pub fn as_millis_f64(&self) -> f64

Returns the number of milliseconds, with a possible fractional nanosecond component, represented by this signed duration as a 64-bit float.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.as_millis_f64(), 12123.456789);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.as_millis_f64(), -12123.456789);

pub fn as_millis_f32(&self) -> f32

Returns the number of milliseconds, with a possible fractional nanosecond component, represented by this signed duration as a 32-bit float.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(duration.as_millis_f32(), 12123.456789);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(duration.as_millis_f32(), -12123.456789);

pub fn from_secs_f64(secs: f64) -> SignedDuration

Returns a signed duration corresponding to the number of seconds represented as a 64-bit float. The number given may have a fractional nanosecond component.

Panics

If the given float overflows the minimum or maximum signed duration values, then this panics.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_secs_f64(12.123456789);
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 123_456_789);

let duration = SignedDuration::from_secs_f64(-12.123456789);
assert_eq!(duration.as_secs(), -12);
assert_eq!(duration.subsec_nanos(), -123_456_789);

pub fn from_secs_f32(secs: f32) -> SignedDuration

Returns a signed duration corresponding to the number of seconds represented as a 32-bit float. The number given may have a fractional nanosecond component.

Panics

If the given float overflows the minimum or maximum signed duration values, then this panics.

Example

use jiff::SignedDuration;

let duration = SignedDuration::from_secs_f32(12.123456789);
assert_eq!(duration.as_secs(), 12);
// loss of precision!
assert_eq!(duration.subsec_nanos(), 123_456_952);

let duration = SignedDuration::from_secs_f32(-12.123456789);
assert_eq!(duration.as_secs(), -12);
// loss of precision!
assert_eq!(duration.subsec_nanos(), -123_456_952);

pub fn try_from_secs_f64(secs: f64) -> Result<SignedDuration, Error>

Returns a signed duration corresponding to the number of seconds represented as a 64-bit float. The number given may have a fractional nanosecond component.

If the given float overflows the minimum or maximum signed duration values, then an error is returned.

Example

use jiff::SignedDuration;

let duration = SignedDuration::try_from_secs_f64(12.123456789)?;
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 123_456_789);

let duration = SignedDuration::try_from_secs_f64(-12.123456789)?;
assert_eq!(duration.as_secs(), -12);
assert_eq!(duration.subsec_nanos(), -123_456_789);

assert!(SignedDuration::try_from_secs_f64(f64::NAN).is_err());
assert!(SignedDuration::try_from_secs_f64(f64::INFINITY).is_err());
assert!(SignedDuration::try_from_secs_f64(f64::NEG_INFINITY).is_err());
assert!(SignedDuration::try_from_secs_f64(f64::MIN).is_err());
assert!(SignedDuration::try_from_secs_f64(f64::MAX).is_err());

pub fn try_from_secs_f32(secs: f32) -> Result<SignedDuration, Error>

Returns a signed duration corresponding to the number of seconds represented as a 32-bit float. The number given may have a fractional nanosecond component.

If the given float overflows the minimum or maximum signed duration values, then an error is returned.

Example

use jiff::SignedDuration;

let duration = SignedDuration::try_from_secs_f32(12.123456789)?;
assert_eq!(duration.as_secs(), 12);
// loss of precision!
assert_eq!(duration.subsec_nanos(), 123_456_952);

let duration = SignedDuration::try_from_secs_f32(-12.123456789)?;
assert_eq!(duration.as_secs(), -12);
// loss of precision!
assert_eq!(duration.subsec_nanos(), -123_456_952);

assert!(SignedDuration::try_from_secs_f32(f32::NAN).is_err());
assert!(SignedDuration::try_from_secs_f32(f32::INFINITY).is_err());
assert!(SignedDuration::try_from_secs_f32(f32::NEG_INFINITY).is_err());
assert!(SignedDuration::try_from_secs_f32(f32::MIN).is_err());
assert!(SignedDuration::try_from_secs_f32(f32::MAX).is_err());

pub fn mul_f64(self, rhs: f64) -> SignedDuration

Returns the result of multiplying this duration by the given 64-bit float.

Panics

This panics if the result is not finite or overflows a SignedDuration.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 300_000_000);
assert_eq!(
    duration.mul_f64(2.0),
    SignedDuration::new(24, 600_000_000),
);
assert_eq!(
    duration.mul_f64(-2.0),
    SignedDuration::new(-24, -600_000_000),
);

pub fn mul_f32(self, rhs: f32) -> SignedDuration

Returns the result of multiplying this duration by the given 32-bit float.

Panics

This panics if the result is not finite or overflows a SignedDuration.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 300_000_000);
assert_eq!(
    duration.mul_f32(2.0),
    // loss of precision!
    SignedDuration::new(24, 600_000_384),
);
assert_eq!(
    duration.mul_f32(-2.0),
    // loss of precision!
    SignedDuration::new(-24, -600_000_384),
);

pub fn div_f64(self, rhs: f64) -> SignedDuration

Returns the result of dividing this duration by the given 64-bit float.

Panics

This panics if the result is not finite or overflows a SignedDuration.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 300_000_000);
assert_eq!(
    duration.div_f64(2.0),
    SignedDuration::new(6, 150_000_000),
);
assert_eq!(
    duration.div_f64(-2.0),
    SignedDuration::new(-6, -150_000_000),
);

pub fn div_f32(self, rhs: f32) -> SignedDuration

Returns the result of dividing this duration by the given 32-bit float.

Panics

This panics if the result is not finite or overflows a SignedDuration.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 300_000_000);
assert_eq!(
    duration.div_f32(2.0),
    // loss of precision!
    SignedDuration::new(6, 150_000_096),
);
assert_eq!(
    duration.div_f32(-2.0),
    // loss of precision!
    SignedDuration::new(-6, -150_000_096),
);

pub fn div_duration_f64(self, rhs: SignedDuration) -> f64

Divides this signed duration by another signed duration and returns the corresponding 64-bit float result.

Example

use jiff::SignedDuration;

let duration1 = SignedDuration::new(12, 600_000_000);
let duration2 = SignedDuration::new(6, 300_000_000);
assert_eq!(duration1.div_duration_f64(duration2), 2.0);

let duration1 = SignedDuration::new(-12, -600_000_000);
let duration2 = SignedDuration::new(6, 300_000_000);
assert_eq!(duration1.div_duration_f64(duration2), -2.0);

let duration1 = SignedDuration::new(-12, -600_000_000);
let duration2 = SignedDuration::new(-6, -300_000_000);
assert_eq!(duration1.div_duration_f64(duration2), 2.0);

pub fn div_duration_f32(self, rhs: SignedDuration) -> f32

Divides this signed duration by another signed duration and returns the corresponding 32-bit float result.

Example

use jiff::SignedDuration;

let duration1 = SignedDuration::new(12, 600_000_000);
let duration2 = SignedDuration::new(6, 300_000_000);
assert_eq!(duration1.div_duration_f32(duration2), 2.0);

let duration1 = SignedDuration::new(-12, -600_000_000);
let duration2 = SignedDuration::new(6, 300_000_000);
assert_eq!(duration1.div_duration_f32(duration2), -2.0);

let duration1 = SignedDuration::new(-12, -600_000_000);
let duration2 = SignedDuration::new(-6, -300_000_000);
assert_eq!(duration1.div_duration_f32(duration2), 2.0);

impl SignedDuration

Additional APIs not found in the standard library.

In most cases, these APIs exist as a result of the fact that this duration is signed.

pub const fn as_hours(&self) -> i64

Returns the number of whole hours in this duration.

The value returned is negative when the duration is negative.

This does not include any fractional component corresponding to units less than an hour.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(86_400, 999_999_999);
assert_eq!(duration.as_hours(), 24);

let duration = SignedDuration::new(-86_400, -999_999_999);
assert_eq!(duration.as_hours(), -24);

pub const fn as_mins(&self) -> i64

Returns the number of whole minutes in this duration.

The value returned is negative when the duration is negative.

This does not include any fractional component corresponding to units less than a minute.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(3_600, 999_999_999);
assert_eq!(duration.as_mins(), 60);

let duration = SignedDuration::new(-3_600, -999_999_999);
assert_eq!(duration.as_mins(), -60);

pub const fn abs(self) -> SignedDuration

Returns the absolute value of this signed duration.

If this duration isn’t negative, then this returns the original duration unchanged.

Panics

This panics when the seconds component of this signed duration is equal to i64::MIN.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(1, -1_999_999_999);
assert_eq!(duration.abs(), SignedDuration::new(0, 999_999_999));

pub const fn unsigned_abs(self) -> Duration

Returns the absolute value of this signed duration as a std::time::Duration. More specifically, this routine cannot panic because the absolute value of SignedDuration::MIN is representable in a std::time::Duration.

Example

use std::time::Duration;

use jiff::SignedDuration;

let duration = SignedDuration::MIN;
assert_eq!(
    duration.unsigned_abs(),
    Duration::new(i64::MIN.unsigned_abs(), 999_999_999),
);

pub const fn checked_neg(self) -> Option<SignedDuration>

Returns this duration with its sign flipped.

If this duration is zero, then this returns the duration unchanged.

This returns none if the negation does not exist. This occurs in precisely the cases when SignedDuration::as_secs is equal to i64::MIN.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(12, 123_456_789);
assert_eq!(
    duration.checked_neg(),
    Some(SignedDuration::new(-12, -123_456_789)),
);

let duration = SignedDuration::new(-12, -123_456_789);
assert_eq!(
    duration.checked_neg(),
    Some(SignedDuration::new(12, 123_456_789)),
);

// Negating the minimum seconds isn't possible.
assert_eq!(SignedDuration::MIN.checked_neg(), None);

pub const fn signum(self) -> i8

Returns a number that represents the sign of this duration.

• When SignedDuration::is_zero is true, this returns 0.
• When SignedDuration::is_positive is true, this returns 1.
• When SignedDuration::is_negative is true, this returns -1.

The above cases are mutually exclusive.

Example

use jiff::SignedDuration;

assert_eq!(0, SignedDuration::ZERO.signum());

pub const fn is_positive(&self) -> bool

Returns true when this duration is positive. That is, greater than SignedDuration::ZERO.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(0, 1);
assert!(duration.is_positive());

pub const fn is_negative(&self) -> bool

Returns true when this duration is negative. That is, less than SignedDuration::ZERO.

Example

use jiff::SignedDuration;

let duration = SignedDuration::new(0, -1);
assert!(duration.is_negative());

impl SignedDuration

Additional APIs for computing the duration between date and time values.

pub fn system_until( time1: SystemTime, time2: SystemTime, ) -> Result<SignedDuration, Error>

Returns the duration from time1 until time2 where the times are std::time::SystemTime values from the standard library.

Errors

This returns an error if the difference between the two time values overflows the signed duration limits.

Example

use std::time::{Duration, SystemTime};
use jiff::SignedDuration;

let time1 = SystemTime::UNIX_EPOCH;
let time2 = time1.checked_add(Duration::from_secs(86_400)).unwrap();
assert_eq!(
    SignedDuration::system_until(time1, time2)?,
    SignedDuration::from_hours(24),
);

impl SignedDuration

Jiff specific APIs.

pub fn round<R>(self, options: R) -> Result<SignedDuration, Error>

where R: Into<SignedDurationRound>,

Returns a new signed duration that is rounded according to the given configuration.

Rounding a duration has a number of parameters, all of which are optional. When no parameters are given, then no rounding is done, and the duration as given is returned. That is, it’s a no-op.

As is consistent with SignedDuration itself, rounding only supports time units, i.e., units of hours or smaller. If a calendar Unit is provided, then an error is returned. In order to round a duration with calendar units, you must use Span::round and provide a relative datetime.

The parameters are, in brief:

• SignedDurationRound::smallest sets the smallest Unit that is allowed to be non-zero in the duration returned. By default, it is set to Unit::Nanosecond, i.e., no rounding occurs. When the smallest unit is set to something bigger than nanoseconds, then the non-zero units in the duration smaller than the smallest unit are used to determine how the duration should be rounded. For example, rounding 1 hour 59 minutes to the nearest hour using the default rounding mode would produce 2 hours.
• SignedDurationRound::mode determines how to handle the remainder when rounding. The default is RoundMode::HalfExpand, which corresponds to how you were likely taught to round in school. Alternative modes, like RoundMode::Trunc, exist too. For example, a truncating rounding of 1 hour 59 minutes to the nearest hour would produce 1 hour.
• SignedDurationRound::increment sets the rounding granularity to use for the configured smallest unit. For example, if the smallest unit is minutes and the increment is 5, then the duration returned will always have its minute units set to a multiple of 5.

Errors

In general, there are two main ways for rounding to fail: an improper configuration like trying to round a duration to the nearest calendar unit, or when overflow occurs. Overflow can occur when the duration would exceed the minimum or maximum SignedDuration values. Typically, this can only realistically happen if the duration before rounding is already close to its minimum or maximum value.

Example: round to the nearest second

This shows how to round a duration to the nearest second. This might be useful when you want to chop off any sub-second component in a way that depends on how close it is (or not) to the next second.

use jiff::{SignedDuration, Unit};

// rounds up
let dur = SignedDuration::new(4 * 60 * 60 + 50 * 60 + 32, 500_000_000);
assert_eq!(
    dur.round(Unit::Second)?,
    SignedDuration::new(4 * 60 * 60 + 50 * 60 + 33, 0),
);
// rounds down
let dur = SignedDuration::new(4 * 60 * 60 + 50 * 60 + 32, 499_999_999);
assert_eq!(
    dur.round(Unit::Second)?,
    SignedDuration::new(4 * 60 * 60 + 50 * 60 + 32, 0),
);

Example: round to the nearest half minute

One can use SignedDurationRound::increment to set the rounding increment:

use jiff::{SignedDuration, SignedDurationRound, Unit};

let options = SignedDurationRound::new()
    .smallest(Unit::Second)
    .increment(30);

// rounds up
let dur = SignedDuration::from_secs(4 * 60 * 60 + 50 * 60 + 15);
assert_eq!(
    dur.round(options)?,
    SignedDuration::from_secs(4 * 60 * 60 + 50 * 60 + 30),
);
// rounds down
let dur = SignedDuration::from_secs(4 * 60 * 60 + 50 * 60 + 14);
assert_eq!(
    dur.round(options)?,
    SignedDuration::from_secs(4 * 60 * 60 + 50 * 60),
);

Example: overflow results in an error

If rounding would result in a value that exceeds a SignedDuration’s minimum or maximum values, then an error occurs:

use jiff::{SignedDuration, Unit};

assert_eq!(
    SignedDuration::MAX.round(Unit::Hour).unwrap_err().to_string(),
    "rounding `2562047788015215h 30m 7s 999ms 999µs 999ns` to \
     nearest hour in increments of 1 resulted in \
     9223372036854777600 seconds, which does not fit into an i64 \
     and thus overflows `SignedDuration`",
);
assert_eq!(
    SignedDuration::MIN.round(Unit::Hour).unwrap_err().to_string(),
    "rounding `2562047788015215h 30m 8s 999ms 999µs 999ns ago` to \
     nearest hour in increments of 1 resulted in \
     -9223372036854777600 seconds, which does not fit into an i64 \
     and thus overflows `SignedDuration`",
);

Example: rounding with a calendar unit results in an error

use jiff::{SignedDuration, Unit};

assert_eq!(
    SignedDuration::ZERO.round(Unit::Day).unwrap_err().to_string(),
    "rounding `SignedDuration` failed \
     because a calendar unit of days was provided \
     (to round by calendar units, you must use a `Span`)",
);

Trait Implementations

impl<'a> Add<SignedDuration> for &'a Zoned

Adds a signed duration of time to a zoned datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_add.

type Output = Zoned

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> Zoned

Performs the + operation.

impl Add<SignedDuration> for Date

Adds a signed duration of time to a date.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_add.

type Output = Date

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> Date

Performs the + operation.

impl Add<SignedDuration> for DateTime

Adds a signed duration of time to a datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_add.

type Output = DateTime

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> DateTime

Performs the + operation.

impl Add<SignedDuration> for Offset

Adds a signed duration of time to an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

type Output = Offset

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> Offset

Performs the + operation.

impl Add<SignedDuration> for Time

Adds a signed duration of time. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_add.

type Output = Time

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> Time

Performs the + operation.

impl Add<SignedDuration> for Timestamp

Adds a signed duration of time to a timestamp.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_add.

type Output = Timestamp

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> Timestamp

Performs the + operation.

impl Add for SignedDuration

type Output = SignedDuration

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> SignedDuration

Performs the + operation.

impl AddAssign<SignedDuration> for Date

Adds a signed duration of time to a date in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_add.

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl AddAssign<SignedDuration> for DateTime

Adds a signed duration of time to a datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_add.

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl AddAssign<SignedDuration> for Offset

Adds a signed duration of time to an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl AddAssign<SignedDuration> for Time

Adds a signed duration of time in place. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_add.

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl AddAssign<SignedDuration> for Timestamp

Adds a signed duration of time to a timestamp in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_add.

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl AddAssign<SignedDuration> for Zoned

Adds a signed duration of time to a zoned datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_add.

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl AddAssign for SignedDuration

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl Clone for SignedDuration

fn clone(&self) -> SignedDuration

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SignedDuration

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

Formats the value using the given formatter.

impl Default for SignedDuration

fn default() -> SignedDuration

Returns the “default value” for a type.

impl Display for SignedDuration

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

Formats the value using the given formatter.

impl Div<i32> for SignedDuration

type Output = SignedDuration

The resulting type after applying the / operator.

fn div(self, rhs: i32) -> SignedDuration

Performs the / operation.

impl DivAssign<i32> for SignedDuration

fn div_assign(&mut self, rhs: i32)

Performs the /= operation.

impl<'a> From<&'a SignedDuration> for DateArithmetic

fn from(sdur: &'a SignedDuration) -> DateArithmetic

Converts to this type from the input type.

impl<'a> From<&'a SignedDuration> for DateTimeArithmetic

fn from(sdur: &'a SignedDuration) -> DateTimeArithmetic

Converts to this type from the input type.

impl<'a> From<&'a SignedDuration> for OffsetArithmetic

fn from(sdur: &'a SignedDuration) -> OffsetArithmetic

Converts to this type from the input type.

impl<'a> From<&'a SignedDuration> for TimeArithmetic

fn from(sdur: &'a SignedDuration) -> TimeArithmetic

Converts to this type from the input type.

impl<'a> From<&'a SignedDuration> for TimestampArithmetic

fn from(sdur: &'a SignedDuration) -> TimestampArithmetic

Converts to this type from the input type.

impl<'a> From<&'a SignedDuration> for ZonedArithmetic

fn from(sdur: &'a SignedDuration) -> ZonedArithmetic

Converts to this type from the input type.

impl From<SignedDuration> for DateArithmetic

fn from(sdur: SignedDuration) -> DateArithmetic

Converts to this type from the input type.

impl From<SignedDuration> for DateTimeArithmetic

fn from(sdur: SignedDuration) -> DateTimeArithmetic

Converts to this type from the input type.

impl From<SignedDuration> for OffsetArithmetic

fn from(sdur: SignedDuration) -> OffsetArithmetic

Converts to this type from the input type.

impl From<SignedDuration> for SpanArithmetic<'static>

fn from(duration: SignedDuration) -> SpanArithmetic<'static>

Converts to this type from the input type.

impl From<SignedDuration> for TimeArithmetic

fn from(sdur: SignedDuration) -> TimeArithmetic

Converts to this type from the input type.

impl From<SignedDuration> for TimestampArithmetic

fn from(sdur: SignedDuration) -> TimestampArithmetic

Converts to this type from the input type.

impl From<SignedDuration> for ZonedArithmetic

fn from(sdur: SignedDuration) -> ZonedArithmetic

Converts to this type from the input type.

impl FromStr for SignedDuration

type Err = Error

The associated error which can be returned from parsing.

fn from_str(string: &str) -> Result<SignedDuration, Error>

Parses a string s to return a value of this type.

impl Hash for SignedDuration

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul<SignedDuration> for i32

type Output = SignedDuration

The resulting type after applying the * operator.

fn mul(self, rhs: SignedDuration) -> SignedDuration

Performs the * operation.

impl Mul<i32> for SignedDuration

type Output = SignedDuration

The resulting type after applying the * operator.

fn mul(self, rhs: i32) -> SignedDuration

Performs the * operation.

impl MulAssign<i32> for SignedDuration

fn mul_assign(&mut self, rhs: i32)

Performs the *= operation.

impl Neg for SignedDuration

type Output = SignedDuration

The resulting type after applying the - operator.

fn neg(self) -> SignedDuration

Performs the unary - operation.

impl Ord for SignedDuration

fn cmp(&self, other: &SignedDuration) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SignedDuration

fn eq(&self, other: &SignedDuration) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for SignedDuration

fn partial_cmp(&self, other: &SignedDuration) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> Sub<SignedDuration> for &'a Zoned

Subtracts a signed duration of time from a zoned datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_sub.

type Output = Zoned

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> Zoned

Performs the - operation.

impl Sub<SignedDuration> for Date

Subtracts a signed duration of time from a date.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_sub.

type Output = Date

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> Date

Performs the - operation.

impl Sub<SignedDuration> for DateTime

Subtracts a signed duration of time from a datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_sub.

type Output = DateTime

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> DateTime

Performs the - operation.

impl Sub<SignedDuration> for Offset

Subtracts a signed duration of time from an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

type Output = Offset

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> Offset

Performs the - operation.

impl Sub<SignedDuration> for Time

Subtracts a signed duration of time. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_sub.

type Output = Time

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> Time

Performs the - operation.

impl Sub<SignedDuration> for Timestamp

Subtracts a signed duration of time from a timestamp.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_sub.

type Output = Timestamp

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> Timestamp

Performs the - operation.

impl Sub for SignedDuration

type Output = SignedDuration

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> SignedDuration

Performs the - operation.

impl SubAssign<SignedDuration> for Date

Subtracts a signed duration of time from a date in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_sub.

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl SubAssign<SignedDuration> for DateTime

Subtracts a signed duration of time from a datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_sub.

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl SubAssign<SignedDuration> for Offset

Subtracts a signed duration of time from an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl SubAssign<SignedDuration> for Time

Subtracts a signed duration of time in place. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_sub.

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl SubAssign<SignedDuration> for Timestamp

Subtracts a signed duration of time from a timestamp in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_sub.

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl SubAssign<SignedDuration> for Zoned

Subtracts a signed duration of time from a zoned datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_sub.

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl SubAssign for SignedDuration

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl TryFrom<Duration> for SignedDuration

type Error = Error

The type returned in the event of a conversion error.

fn try_from(d: Duration) -> Result<SignedDuration, Error>

Performs the conversion.

impl TryFrom<SignedDuration> for Duration

type Error = Error

The type returned in the event of a conversion error.

fn try_from(sd: SignedDuration) -> Result<Duration, Error>

Performs the conversion.

impl TryFrom<SignedDuration> for Span

Converts a SignedDuration to a Span.

The span returned from this conversion will only ever have non-zero units of seconds or smaller.

Errors

This only fails when the given SignedDuration overflows the maximum number of seconds representable by a Span.

Example

This shows a basic conversion:

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

let duration = SignedDuration::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,
    86_400.seconds().milliseconds(123).microseconds(456).nanoseconds(789),
);

Example: rounding

This example shows how to convert a SignedDuration to a Span, and then round it up to bigger units given a relative date:

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

let duration = SignedDuration::new(450 * 86_401, 0);
let span = Span::try_from(duration)?;
// We get back a simple span of just seconds:
assert_eq!(span, Span::new().seconds(450 * 86_401));
// But we can balance it up to bigger units:
let options = SpanRound::new()
    .largest(Unit::Year)
    .relative(date(2024, 1, 1));
assert_eq!(
    span.round(options)?,
    1.year().months(2).days(25).minutes(7).seconds(30),
);

type Error = Error

The type returned in the event of a conversion error.

fn try_from(d: SignedDuration) -> Result<Span, Error>

Performs the conversion.

impl TryFrom<Span> for SignedDuration

Converts a Span to a SignedDuration.

Note that this assumes that days are always 24 hours long.

Errors

This can fail for only when the span has any non-zero units greater than days. This is an error because it’s impossible to determine the length of, e.g., a month without a reference date.

This can never result in overflow because a SignedDuration can represent a bigger span of time than Span when limited to units of days or lower.

If you need to convert a Span to a SignedDuration that has non-zero units bigger than days (or a Span with days of non-uniform length), then please use Span::to_jiff_duration with a corresponding relative date.

Example: maximal span

This example shows the maximum possible span using units of days or smaller, and the corresponding SignedDuration value:

use jiff::{SignedDuration, Span};

let sp = Span::new()
    .days(7_304_484)
    .hours(175_307_616)
    .minutes(10_518_456_960i64)
    .seconds(631_107_417_600i64)
    .milliseconds(631_107_417_600_000i64)
    .microseconds(631_107_417_600_000_000i64)
    .nanoseconds(9_223_372_036_854_775_807i64);
let duration = SignedDuration::try_from(sp)?;
assert_eq!(duration, SignedDuration::new(3_795_867_877_636, 854_775_807));

type Error = Error

The type returned in the event of a conversion error.

fn try_from(sp: Span) -> Result<SignedDuration, Error>

Performs the conversion.

impl Copy for SignedDuration

impl Eq for SignedDuration

impl StructuralPartialEq for SignedDuration