Struct chrono::Duration

pub struct Duration { /* private fields */ }

ISO 8601 time duration with nanosecond precision.

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

Implementations

impl Duration

pub fn weeks(weeks: i64) -> Duration

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.

pub fn days(days: i64) -> Duration

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.

pub fn hours(hours: i64) -> Duration

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.

pub fn minutes(minutes: i64) -> Duration

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.

pub fn seconds(seconds: i64) -> Duration

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.

pub const fn milliseconds(milliseconds: i64) -> Duration

Makes a new Duration with given number of milliseconds.

pub const fn microseconds(microseconds: i64) -> Duration

Makes a new Duration with given number of microseconds.

pub const fn nanoseconds(nanos: i64) -> Duration

Makes a new Duration with given number of nanoseconds.

pub const fn num_weeks(&self) -> i64

Returns the total number of whole weeks in the duration.

pub const fn num_days(&self) -> i64

Returns the total number of whole days in the duration.

pub const fn num_hours(&self) -> i64

Returns the total number of whole hours in the duration.

pub const fn num_minutes(&self) -> i64

Returns the total number of whole minutes in the duration.

pub const fn num_seconds(&self) -> i64

Returns the total number of whole seconds in the duration.

pub const fn num_milliseconds(&self) -> i64

Returns the total number of whole milliseconds in the duration,

pub const fn num_microseconds(&self) -> Option<i64>

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

pub const fn num_nanoseconds(&self) -> Option<i64>

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

pub fn checked_add(&self, rhs: &Duration) -> Option<Duration>

Add two durations, returning None if overflow occurred.

pub fn checked_sub(&self, rhs: &Duration) -> Option<Duration>

Subtract two durations, returning None if overflow occurred.

pub const fn abs(&self) -> Duration

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

pub const fn min_value() -> Duration

The minimum possible Duration: i64::MIN milliseconds.

pub const fn max_value() -> Duration

The maximum possible Duration: i64::MAX milliseconds.

pub const fn zero() -> Duration

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

pub const fn is_zero(&self) -> bool

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

pub fn from_std(duration: StdDuration) -> Result<Duration, OutOfRangeError>

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.

pub fn to_std(&self) -> Result<StdDuration, OutOfRangeError>

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

impl<Tz: TimeZone> Add<Duration> for Date<Tz>

type Output = Date<Tz>

The resulting type after applying the + operator.

fn add(self, rhs: OldDuration) -> Date<Tz>

Performs the + operation.

impl<Tz: TimeZone> Add<Duration> for DateTime<Tz>

type Output = DateTime<Tz>

The resulting type after applying the + operator.

fn add(self, rhs: OldDuration) -> DateTime<Tz>

Performs the + operation.

impl Add<Duration> for Duration

type Output = Duration

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Duration> for NaiveDate

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 = NaiveDate::from_ymd;

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

type Output = NaiveDate

The resulting type after applying the + operator.

fn add(self, rhs: OldDuration) -> NaiveDate

Performs the + operation.

impl Add<Duration> for NaiveDateTime

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 = NaiveDate::from_ymd;

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

type Output = NaiveDateTime

The resulting type after applying the + operator.

fn add(self, rhs: OldDuration) -> NaiveDateTime

Performs the + operation.

impl Add<Duration> for NaiveTime

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 = NaiveTime::from_hms_milli;

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

type Output = NaiveTime

The resulting type after applying the + operator.

fn add(self, rhs: OldDuration) -> NaiveTime

Performs the + operation.

impl<Tz: TimeZone> AddAssign<Duration> for Date<Tz>

fn add_assign(&mut self, rhs: OldDuration)

Performs the += operation.

impl<Tz: TimeZone> AddAssign<Duration> for DateTime<Tz>

fn add_assign(&mut self, rhs: OldDuration)

Performs the += operation.

impl AddAssign<Duration> for NaiveDate

fn add_assign(&mut self, rhs: OldDuration)

Performs the += operation.

impl AddAssign<Duration> for NaiveDateTime

fn add_assign(&mut self, rhs: OldDuration)

Performs the += operation.

impl AddAssign<Duration> for NaiveTime

fn add_assign(&mut self, rhs: OldDuration)

Performs the += operation.

impl Clone for Duration

fn clone(&self) -> Duration

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Duration

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

Formats the value using the given formatter.

impl Display for Duration

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

Format a duration using the ISO 8601 format

impl Div<i32> for Duration

type Output = Duration

The resulting type after applying the / operator.

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

Performs the / operation.

impl Hash for Duration

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

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<i32> for Duration

type Output = Duration

The resulting type after applying the * operator.

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

Performs the * operation.

impl Neg for Duration

type Output = Duration

The resulting type after applying the - operator.

fn neg(self) -> Duration

Performs the unary - operation.

impl Ord for Duration

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Duration> for Duration

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd<Duration> for Duration

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<Tz: TimeZone> Sub<Duration> for Date<Tz>

type Output = Date<Tz>

The resulting type after applying the - operator.

fn sub(self, rhs: OldDuration) -> Date<Tz>

Performs the - operation.

impl<Tz: TimeZone> Sub<Duration> for DateTime<Tz>

type Output = DateTime<Tz>

The resulting type after applying the - operator.

fn sub(self, rhs: OldDuration) -> DateTime<Tz>

Performs the - operation.

impl Sub<Duration> for Duration

type Output = Duration

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for NaiveDate

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 = NaiveDate::from_ymd;

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

type Output = NaiveDate

The resulting type after applying the - operator.

fn sub(self, rhs: OldDuration) -> NaiveDate

Performs the - operation.

impl Sub<Duration> for NaiveDateTime

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 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_sub_signed to detect that.

Example

use chrono::{Duration, NaiveDate};

let from_ymd = NaiveDate::from_ymd;

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

type Output = NaiveDateTime

The resulting type after applying the - operator.

fn sub(self, rhs: OldDuration) -> NaiveDateTime

Performs the - operation.

impl Sub<Duration> for NaiveTime

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 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 = NaiveTime::from_hms_milli;

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

type Output = NaiveTime

The resulting type after applying the - operator.

fn sub(self, rhs: OldDuration) -> NaiveTime

Performs the - operation.

impl<Tz: TimeZone> SubAssign<Duration> for Date<Tz>

fn sub_assign(&mut self, rhs: OldDuration)

Performs the -= operation.

impl<Tz: TimeZone> SubAssign<Duration> for DateTime<Tz>

fn sub_assign(&mut self, rhs: OldDuration)

Performs the -= operation.

impl SubAssign<Duration> for NaiveDate

fn sub_assign(&mut self, rhs: OldDuration)

Performs the -= operation.

impl SubAssign<Duration> for NaiveDateTime

fn sub_assign(&mut self, rhs: OldDuration)

Performs the -= operation.

impl SubAssign<Duration> for NaiveTime

fn sub_assign(&mut self, rhs: OldDuration)

Performs the -= operation.

impl<'a> Sum<&'a Duration> for Duration

fn sum<I: Iterator<Item = &'a Duration>>(iter: I) -> Duration

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl Sum<Duration> for Duration

fn sum<I: Iterator<Item = Duration>>(iter: I) -> Duration

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl Copy for Duration

impl Eq for Duration

impl StructuralEq for Duration

impl StructuralPartialEq for Duration