Struct chrono::Duration

source · [−]
pub struct Duration { /* private fields */ }
Expand description

ISO 8601 time duration with nanosecond precision.

This also allows for the negative duration; see individual methods for details.

Implementations

Makes a new Duration with given number of weeks. Equivalent to Duration::seconds(weeks * 7 * 24 * 60 * 60) with overflow checks. Panics when the duration is out of bounds.

Makes a new Duration with given number of days. Equivalent to Duration::seconds(days * 24 * 60 * 60) with overflow checks. Panics when the duration is out of bounds.

Makes a new Duration with given number of hours. Equivalent to Duration::seconds(hours * 60 * 60) with overflow checks. Panics when the duration is out of bounds.

Makes a new Duration with given number of minutes. Equivalent to Duration::seconds(minutes * 60) with overflow checks. Panics when the duration is out of bounds.

Makes a new Duration with given number of seconds. Panics when the duration is more than i64::MAX seconds or less than i64::MIN seconds.

Makes a new Duration with given number of milliseconds.

Makes a new Duration with given number of microseconds.

Makes a new Duration with given number of nanoseconds.

Returns the total number of whole weeks in the duration.

Returns the total number of whole days in the duration.

Returns the total number of whole hours in the duration.

Returns the total number of whole minutes in the duration.

Returns the total number of whole seconds in the duration.

Returns the total number of whole milliseconds in the duration,

Returns the total number of whole microseconds in the duration, or None on overflow (exceeding 2^63 microseconds in either direction).

Returns the total number of whole nanoseconds in the duration, or None on overflow (exceeding 2^63 nanoseconds in either direction).

Add two durations, returning None if overflow occurred.

Subtract two durations, returning None if overflow occurred.

Returns the duration as an absolute (non-negative) value.

The minimum possible Duration: i64::MIN milliseconds.

The maximum possible Duration: i64::MAX milliseconds.

A duration where the stored seconds and nanoseconds are equal to zero.

Returns true if the duration equals Duration::zero().

Creates a time::Duration object from std::time::Duration

This function errors when original duration is larger than the maximum value supported for this type.

Creates a std::time::Duration object from time::Duration

This function errors when duration is less than zero. As standard library implementation is limited to non-negative values.

Trait Implementations

The resulting type after applying the + operator.
Performs the + operation. Read more
The resulting type after applying the + operator.
Performs the + operation. Read more
The resulting type after applying the + operator.
Performs the + operation. Read more

An addition of Duration to NaiveDate discards the fractional days, rounding to the closest integral number of days towards Duration::zero().

Panics on underflow or overflow. Use NaiveDate::checked_add_signed to detect that.

Example

use chrono::{Duration, NaiveDate};

let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();

assert_eq!(from_ymd(2014, 1, 1) + Duration::zero(),             from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) + Duration::seconds(86399),     from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) + Duration::seconds(-86399),    from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) + Duration::days(1),            from_ymd(2014, 1, 2));
assert_eq!(from_ymd(2014, 1, 1) + Duration::days(-1),           from_ymd(2013, 12, 31));
assert_eq!(from_ymd(2014, 1, 1) + Duration::days(364),          from_ymd(2014, 12, 31));
assert_eq!(from_ymd(2014, 1, 1) + Duration::days(365*4 + 1),    from_ymd(2018, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) + Duration::days(365*400 + 97), from_ymd(2414, 1, 1));
The resulting type after applying the + operator.
Performs the + operation. Read more

An addition of Duration to NaiveDateTime yields another NaiveDateTime.

As a part of Chrono’s leap second handling, the addition assumes that there is no leap second ever, except when the NaiveDateTime itself represents a leap second in which case the assumption becomes that there is exactly a single leap second ever.

Panics on underflow or overflow. Use NaiveDateTime::checked_add_signed to detect that.

Example

use chrono::{Duration, NaiveDate};

let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();

let d = from_ymd(2016, 7, 8);
let hms = |h, m, s| d.and_hms_opt(h, m, s).unwrap();
assert_eq!(hms(3, 5, 7) + Duration::zero(),             hms(3, 5, 7));
assert_eq!(hms(3, 5, 7) + Duration::seconds(1),         hms(3, 5, 8));
assert_eq!(hms(3, 5, 7) + Duration::seconds(-1),        hms(3, 5, 6));
assert_eq!(hms(3, 5, 7) + Duration::seconds(3600 + 60), hms(4, 6, 7));
assert_eq!(hms(3, 5, 7) + Duration::seconds(86_400),
           from_ymd(2016, 7, 9).and_hms_opt(3, 5, 7).unwrap());
assert_eq!(hms(3, 5, 7) + Duration::days(365),
           from_ymd(2017, 7, 8).and_hms_opt(3, 5, 7).unwrap());

let hmsm = |h, m, s, milli| d.and_hms_milli_opt(h, m, s, milli).unwrap();
assert_eq!(hmsm(3, 5, 7, 980) + Duration::milliseconds(450), hmsm(3, 5, 8, 430));

Leap seconds are handled, but the addition assumes that it is the only leap second happened.

let leap = hmsm(3, 5, 59, 1_300);
assert_eq!(leap + Duration::zero(),             hmsm(3, 5, 59, 1_300));
assert_eq!(leap + Duration::milliseconds(-500), hmsm(3, 5, 59, 800));
assert_eq!(leap + Duration::milliseconds(500),  hmsm(3, 5, 59, 1_800));
assert_eq!(leap + Duration::milliseconds(800),  hmsm(3, 6, 0, 100));
assert_eq!(leap + Duration::seconds(10),        hmsm(3, 6, 9, 300));
assert_eq!(leap + Duration::seconds(-10),       hmsm(3, 5, 50, 300));
assert_eq!(leap + Duration::days(1),
           from_ymd(2016, 7, 9).and_hms_milli_opt(3, 5, 59, 300).unwrap());
The resulting type after applying the + operator.
Performs the + operation. Read more

An addition of Duration to NaiveTime wraps around and never overflows or underflows. In particular the addition ignores integral number of days.

As a part of Chrono’s leap second handling, the addition assumes that there is no leap second ever, except when the NaiveTime itself represents a leap second in which case the assumption becomes that there is exactly a single leap second ever.

Example

use chrono::{Duration, NaiveTime};

let from_hmsm = |h, m, s, milli| { NaiveTime::from_hms_milli_opt(h, m, s, milli).unwrap() };

assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::zero(),                  from_hmsm(3, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(1),              from_hmsm(3, 5, 8, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(-1),             from_hmsm(3, 5, 6, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(60 + 4),         from_hmsm(3, 6, 11, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(7*60*60 - 6*60), from_hmsm(9, 59, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::milliseconds(80),        from_hmsm(3, 5, 7, 80));
assert_eq!(from_hmsm(3, 5, 7, 950) + Duration::milliseconds(280),     from_hmsm(3, 5, 8, 230));
assert_eq!(from_hmsm(3, 5, 7, 950) + Duration::milliseconds(-980),    from_hmsm(3, 5, 6, 970));

The addition wraps around.

assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(22*60*60), from_hmsm(1, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(-8*60*60), from_hmsm(19, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::days(800),         from_hmsm(3, 5, 7, 0));

Leap seconds are handled, but the addition assumes that it is the only leap second happened.

let leap = from_hmsm(3, 5, 59, 1_300);
assert_eq!(leap + Duration::zero(),             from_hmsm(3, 5, 59, 1_300));
assert_eq!(leap + Duration::milliseconds(-500), from_hmsm(3, 5, 59, 800));
assert_eq!(leap + Duration::milliseconds(500),  from_hmsm(3, 5, 59, 1_800));
assert_eq!(leap + Duration::milliseconds(800),  from_hmsm(3, 6, 0, 100));
assert_eq!(leap + Duration::seconds(10),        from_hmsm(3, 6, 9, 300));
assert_eq!(leap + Duration::seconds(-10),       from_hmsm(3, 5, 50, 300));
assert_eq!(leap + Duration::days(1),            from_hmsm(3, 5, 59, 300));
The resulting type after applying the + operator.
Performs the + operation. Read more
Performs the += operation. Read more
Performs the += operation. Read more
Performs the += operation. Read more
Performs the += operation. Read more
Performs the += operation. Read more
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more

Format a duration using the ISO 8601 format

The resulting type after applying the / operator.
Performs the / operation. Read more
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more
The resulting type after applying the * operator.
Performs the * operation. Read more
The resulting type after applying the - operator.
Performs the unary - operation. Read more
This method returns an Ordering between self and other. Read more
Compares and returns the maximum of two values. Read more
Compares and returns the minimum of two values. Read more
Restrict a value to a certain interval. Read more
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more

A subtraction of Duration from NaiveDate discards the fractional days, rounding to the closest integral number of days towards Duration::zero(). It is the same as the addition with a negated Duration.

Panics on underflow or overflow. Use NaiveDate::checked_sub_signed to detect that.

Example

use chrono::{Duration, NaiveDate};

let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();

assert_eq!(from_ymd(2014, 1, 1) - Duration::zero(),             from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) - Duration::seconds(86399),     from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) - Duration::seconds(-86399),    from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) - Duration::days(1),            from_ymd(2013, 12, 31));
assert_eq!(from_ymd(2014, 1, 1) - Duration::days(-1),           from_ymd(2014, 1, 2));
assert_eq!(from_ymd(2014, 1, 1) - Duration::days(364),          from_ymd(2013, 1, 2));
assert_eq!(from_ymd(2014, 1, 1) - Duration::days(365*4 + 1),    from_ymd(2010, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) - Duration::days(365*400 + 97), from_ymd(1614, 1, 1));
The resulting type after applying the - operator.
Performs the - operation. Read more

A subtraction of Duration from NaiveDateTime yields another NaiveDateTime. It is the same as the addition with a negated Duration.

As a part of Chrono’s leap second handling the subtraction assumes that there is no leap second ever, except when the NaiveDateTime itself represents a leap second in which case the assumption becomes that there is exactly a single leap second ever.

Panics on underflow or overflow. Use NaiveDateTime::checked_sub_signed to detect that.

Example

use chrono::{Duration, NaiveDate};

let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();

let d = from_ymd(2016, 7, 8);
let hms = |h, m, s| d.and_hms_opt(h, m, s).unwrap();
assert_eq!(hms(3, 5, 7) - Duration::zero(),             hms(3, 5, 7));
assert_eq!(hms(3, 5, 7) - Duration::seconds(1),         hms(3, 5, 6));
assert_eq!(hms(3, 5, 7) - Duration::seconds(-1),        hms(3, 5, 8));
assert_eq!(hms(3, 5, 7) - Duration::seconds(3600 + 60), hms(2, 4, 7));
assert_eq!(hms(3, 5, 7) - Duration::seconds(86_400),
           from_ymd(2016, 7, 7).and_hms_opt(3, 5, 7).unwrap());
assert_eq!(hms(3, 5, 7) - Duration::days(365),
           from_ymd(2015, 7, 9).and_hms_opt(3, 5, 7).unwrap());

let hmsm = |h, m, s, milli| d.and_hms_milli_opt(h, m, s, milli).unwrap();
assert_eq!(hmsm(3, 5, 7, 450) - Duration::milliseconds(670), hmsm(3, 5, 6, 780));

Leap seconds are handled, but the subtraction assumes that it is the only leap second happened.

let leap = hmsm(3, 5, 59, 1_300);
assert_eq!(leap - Duration::zero(),            hmsm(3, 5, 59, 1_300));
assert_eq!(leap - Duration::milliseconds(200), hmsm(3, 5, 59, 1_100));
assert_eq!(leap - Duration::milliseconds(500), hmsm(3, 5, 59, 800));
assert_eq!(leap - Duration::seconds(60),       hmsm(3, 5, 0, 300));
assert_eq!(leap - Duration::days(1),
           from_ymd(2016, 7, 7).and_hms_milli_opt(3, 6, 0, 300).unwrap());
The resulting type after applying the - operator.
Performs the - operation. Read more

A subtraction of Duration from NaiveTime wraps around and never overflows or underflows. In particular the addition ignores integral number of days. It is the same as the addition with a negated Duration.

As a part of Chrono’s leap second handling, the subtraction assumes that there is no leap second ever, except when the NaiveTime itself represents a leap second in which case the assumption becomes that there is exactly a single leap second ever.

Example

use chrono::{Duration, NaiveTime};

let from_hmsm = |h, m, s, milli| { NaiveTime::from_hms_milli_opt(h, m, s, milli).unwrap() };

assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::zero(),                  from_hmsm(3, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(1),              from_hmsm(3, 5, 6, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(60 + 5),         from_hmsm(3, 4, 2, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(2*60*60 + 6*60), from_hmsm(0, 59, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::milliseconds(80),        from_hmsm(3, 5, 6, 920));
assert_eq!(from_hmsm(3, 5, 7, 950) - Duration::milliseconds(280),     from_hmsm(3, 5, 7, 670));

The subtraction wraps around.

assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(8*60*60), from_hmsm(19, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::days(800),        from_hmsm(3, 5, 7, 0));

Leap seconds are handled, but the subtraction assumes that it is the only leap second happened.

let leap = from_hmsm(3, 5, 59, 1_300);
assert_eq!(leap - Duration::zero(),            from_hmsm(3, 5, 59, 1_300));
assert_eq!(leap - Duration::milliseconds(200), from_hmsm(3, 5, 59, 1_100));
assert_eq!(leap - Duration::milliseconds(500), from_hmsm(3, 5, 59, 800));
assert_eq!(leap - Duration::seconds(60),       from_hmsm(3, 5, 0, 300));
assert_eq!(leap - Duration::days(1),           from_hmsm(3, 6, 0, 300));
The resulting type after applying the - operator.
Performs the - operation. Read more
Performs the -= operation. Read more
Performs the -= operation. Read more
Performs the -= operation. Read more
Performs the -= operation. Read more
Performs the -= operation. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.