Struct chrono::time_delta::TimeDelta

pub struct TimeDelta {
    secs: i64,
    nanos: i32,
}

Time duration with nanosecond precision.

This also allows for negative durations; see individual methods for details.

A TimeDelta is represented internally as a complement of seconds and nanoseconds. The range is restricted to that of i64 milliseconds, with the minimum value notably being set to -i64::MAX rather than allowing the full range of i64::MIN. This is to allow easy flipping of sign, so that for instance abs() can be called without any checks.

Fields

secs: i64

nanos: i32

Implementations

impl TimeDelta

pub const fn new(secs: i64, nanos: u32) -> Option<TimeDelta>

Makes a new TimeDelta with given number of seconds and nanoseconds.

Errors

Returns None when the duration is out of bounds, or if nanos ≥ 1,000,000,000.

pub const fn weeks(weeks: i64) -> TimeDelta

Makes a new TimeDelta with the given number of weeks.

Equivalent to TimeDelta::seconds(weeks * 7 * 24 * 60 * 60) with overflow checks.

Panics

Panics when the duration is out of bounds.

pub const fn try_weeks(weeks: i64) -> Option<TimeDelta>

Makes a new TimeDelta with the given number of weeks.

Equivalent to TimeDelta::try_seconds(weeks * 7 * 24 * 60 * 60) with overflow checks.

Errors

Returns None when the TimeDelta would be out of bounds.

pub const fn days(days: i64) -> TimeDelta

Makes a new TimeDelta with the given number of days.

Equivalent to TimeDelta::seconds(days * 24 * 60 * 60) with overflow checks.

Panics

Panics when the TimeDelta would be out of bounds.

pub const fn try_days(days: i64) -> Option<TimeDelta>

Makes a new TimeDelta with the given number of days.

Equivalent to TimeDelta::try_seconds(days * 24 * 60 * 60) with overflow checks.

Errors

Returns None when the TimeDelta would be out of bounds.

pub const fn hours(hours: i64) -> TimeDelta

Makes a new TimeDelta with the given number of hours.

Equivalent to TimeDelta::seconds(hours * 60 * 60) with overflow checks.

Panics

Panics when the TimeDelta would be out of bounds.

pub const fn try_hours(hours: i64) -> Option<TimeDelta>

Makes a new TimeDelta with the given number of hours.

Equivalent to TimeDelta::try_seconds(hours * 60 * 60) with overflow checks.

Errors

Returns None when the TimeDelta would be out of bounds.

pub const fn minutes(minutes: i64) -> TimeDelta

Makes a new TimeDelta with the given number of minutes.

Equivalent to TimeDelta::seconds(minutes * 60) with overflow checks.

Panics

Panics when the TimeDelta would be out of bounds.

pub const fn try_minutes(minutes: i64) -> Option<TimeDelta>

Makes a new TimeDelta with the given number of minutes.

Equivalent to TimeDelta::try_seconds(minutes * 60) with overflow checks.

Errors

Returns None when the TimeDelta would be out of bounds.

pub const fn seconds(seconds: i64) -> TimeDelta

Makes a new TimeDelta with the given number of seconds.

Panics

Panics when seconds is more than i64::MAX / 1_000 or less than -i64::MAX / 1_000 (in this context, this is the same as i64::MIN / 1_000 due to rounding).

pub const fn try_seconds(seconds: i64) -> Option<TimeDelta>

Makes a new TimeDelta with the given number of seconds.

Errors

Returns None when seconds is more than i64::MAX / 1_000 or less than -i64::MAX / 1_000 (in this context, this is the same as i64::MIN / 1_000 due to rounding).

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

Makes a new TimeDelta with the given number of milliseconds.

Panics

Panics when the TimeDelta would be out of bounds, i.e. when milliseconds is more than i64::MAX or less than -i64::MAX. Notably, this is not the same as i64::MIN.

pub const fn try_milliseconds(milliseconds: i64) -> Option<TimeDelta>

Makes a new TimeDelta with the given number of milliseconds.

Errors

Returns None the TimeDelta would be out of bounds, i.e. when milliseconds is more than i64::MAX or less than -i64::MAX. Notably, this is not the same as i64::MIN.

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

Makes a new TimeDelta with the given number of microseconds.

The number of microseconds acceptable by this constructor is less than the total number that can actually be stored in a TimeDelta, so it is not possible to specify a value that would be out of bounds. This function is therefore infallible.

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

Makes a new TimeDelta with the given number of nanoseconds.

The number of nanoseconds acceptable by this constructor is less than the total number that can actually be stored in a TimeDelta, so it is not possible to specify a value that would be out of bounds. This function is therefore infallible.

pub const fn num_weeks(&self) -> i64

Returns the total number of whole weeks in the TimeDelta.

pub const fn num_days(&self) -> i64

Returns the total number of whole days in the TimeDelta.

pub const fn num_hours(&self) -> i64

Returns the total number of whole hours in the TimeDelta.

pub const fn num_minutes(&self) -> i64

Returns the total number of whole minutes in the TimeDelta.

pub const fn num_seconds(&self) -> i64

Returns the total number of whole seconds in the TimeDelta.

pub const fn subsec_nanos(&self) -> i32

Returns the number of nanoseconds such that subsec_nanos() + num_seconds() * NANOS_PER_SEC is the total number of nanoseconds in the TimeDelta.

pub const fn num_milliseconds(&self) -> i64

Returns the total number of whole milliseconds in the TimeDelta.

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

Returns the total number of whole microseconds in the TimeDelta, 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 TimeDelta, or None on overflow (exceeding 2^63 nanoseconds in either direction).

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

Add two TimeDeltas, returning None if overflow occurred.

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

Subtract two TimeDeltas, returning None if overflow occurred.

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

Multiply a TimeDelta with a i32, returning None if overflow occurred.

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

Divide a TimeDelta with a i32, returning None if dividing by 0.

pub const fn abs(&self) -> TimeDelta

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

pub const fn min_value() -> TimeDelta

The minimum possible TimeDelta: -i64::MAX milliseconds.

pub const fn max_value() -> TimeDelta

The maximum possible TimeDelta: i64::MAX milliseconds.

pub const fn zero() -> TimeDelta

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

pub const fn is_zero(&self) -> bool

Returns true if the TimeDelta equals TimeDelta::zero().

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

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

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

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

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

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

pub(crate) const fn neg(self) -> TimeDelta

This duplicates Neg::neg because trait methods can’t be const yet.

Trait Implementations

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

type Output = Date<Tz>

The resulting type after applying the + operator.

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

Performs the + operation.

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

Add TimeDelta to DateTime.

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

Panics if the resulting date would be out of range. Consider using DateTime<Tz>::checked_add_signed to get an Option instead.

type Output = DateTime<Tz>

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<TimeDelta> for NaiveDate

Add TimeDelta to NaiveDate.

This discards the fractional days in TimeDelta, rounding to the closest integral number of days towards TimeDelta::zero().

Panics

Panics if the resulting date would be out of range. Consider using NaiveDate::checked_add_signed to get an Option instead.

Example

use chrono::{NaiveDate, TimeDelta};

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

assert_eq!(from_ymd(2014, 1, 1) + TimeDelta::zero(), from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) + TimeDelta::try_seconds(86399).unwrap(), from_ymd(2014, 1, 1));
assert_eq!(
    from_ymd(2014, 1, 1) + TimeDelta::try_seconds(-86399).unwrap(),
    from_ymd(2014, 1, 1)
);
assert_eq!(from_ymd(2014, 1, 1) + TimeDelta::try_days(1).unwrap(), from_ymd(2014, 1, 2));
assert_eq!(from_ymd(2014, 1, 1) + TimeDelta::try_days(-1).unwrap(), from_ymd(2013, 12, 31));
assert_eq!(from_ymd(2014, 1, 1) + TimeDelta::try_days(364).unwrap(), from_ymd(2014, 12, 31));
assert_eq!(
    from_ymd(2014, 1, 1) + TimeDelta::try_days(365 * 4 + 1).unwrap(),
    from_ymd(2018, 1, 1)
);
assert_eq!(
    from_ymd(2014, 1, 1) + TimeDelta::try_days(365 * 400 + 97).unwrap(),
    from_ymd(2414, 1, 1)
);

type Output = NaiveDate

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<TimeDelta> for NaiveDateTime

Add TimeDelta to 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

Panics if the resulting date would be out of range. Consider using NaiveDateTime::checked_add_signed to get an Option instead.

Example

use chrono::{NaiveDate, TimeDelta};

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) + TimeDelta::zero(), hms(3, 5, 7));
assert_eq!(hms(3, 5, 7) + TimeDelta::try_seconds(1).unwrap(), hms(3, 5, 8));
assert_eq!(hms(3, 5, 7) + TimeDelta::try_seconds(-1).unwrap(), hms(3, 5, 6));
assert_eq!(hms(3, 5, 7) + TimeDelta::try_seconds(3600 + 60).unwrap(), hms(4, 6, 7));
assert_eq!(
    hms(3, 5, 7) + TimeDelta::try_seconds(86_400).unwrap(),
    from_ymd(2016, 7, 9).and_hms_opt(3, 5, 7).unwrap()
);
assert_eq!(
    hms(3, 5, 7) + TimeDelta::try_days(365).unwrap(),
    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) + TimeDelta::try_milliseconds(450).unwrap(), 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 + TimeDelta::zero(), hmsm(3, 5, 59, 1_300));
assert_eq!(leap + TimeDelta::try_milliseconds(-500).unwrap(), hmsm(3, 5, 59, 800));
assert_eq!(leap + TimeDelta::try_milliseconds(500).unwrap(), hmsm(3, 5, 59, 1_800));
assert_eq!(leap + TimeDelta::try_milliseconds(800).unwrap(), hmsm(3, 6, 0, 100));
assert_eq!(leap + TimeDelta::try_seconds(10).unwrap(), hmsm(3, 6, 9, 300));
assert_eq!(leap + TimeDelta::try_seconds(-10).unwrap(), hmsm(3, 5, 50, 300));
assert_eq!(leap + TimeDelta::try_days(1).unwrap(),
           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: TimeDelta) -> NaiveDateTime

Performs the + operation.

impl Add<TimeDelta> for NaiveTime

Add TimeDelta to NaiveTime.

This 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::{NaiveTime, TimeDelta};

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) + TimeDelta::zero(), from_hmsm(3, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + TimeDelta::try_seconds(1).unwrap(), from_hmsm(3, 5, 8, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + TimeDelta::try_seconds(-1).unwrap(), from_hmsm(3, 5, 6, 0));
assert_eq!(
    from_hmsm(3, 5, 7, 0) + TimeDelta::try_seconds(60 + 4).unwrap(),
    from_hmsm(3, 6, 11, 0)
);
assert_eq!(
    from_hmsm(3, 5, 7, 0) + TimeDelta::try_seconds(7 * 60 * 60 - 6 * 60).unwrap(),
    from_hmsm(9, 59, 7, 0)
);
assert_eq!(
    from_hmsm(3, 5, 7, 0) + TimeDelta::try_milliseconds(80).unwrap(),
    from_hmsm(3, 5, 7, 80)
);
assert_eq!(
    from_hmsm(3, 5, 7, 950) + TimeDelta::try_milliseconds(280).unwrap(),
    from_hmsm(3, 5, 8, 230)
);
assert_eq!(
    from_hmsm(3, 5, 7, 950) + TimeDelta::try_milliseconds(-980).unwrap(),
    from_hmsm(3, 5, 6, 970)
);

The addition wraps around.

assert_eq!(from_hmsm(3, 5, 7, 0) + TimeDelta::try_seconds(22*60*60).unwrap(), from_hmsm(1, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + TimeDelta::try_seconds(-8*60*60).unwrap(), from_hmsm(19, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) + TimeDelta::try_days(800).unwrap(), 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 + TimeDelta::zero(), from_hmsm(3, 5, 59, 1_300));
assert_eq!(leap + TimeDelta::try_milliseconds(-500).unwrap(), from_hmsm(3, 5, 59, 800));
assert_eq!(leap + TimeDelta::try_milliseconds(500).unwrap(), from_hmsm(3, 5, 59, 1_800));
assert_eq!(leap + TimeDelta::try_milliseconds(800).unwrap(), from_hmsm(3, 6, 0, 100));
assert_eq!(leap + TimeDelta::try_seconds(10).unwrap(), from_hmsm(3, 6, 9, 300));
assert_eq!(leap + TimeDelta::try_seconds(-10).unwrap(), from_hmsm(3, 5, 50, 300));
assert_eq!(leap + TimeDelta::try_days(1).unwrap(), from_hmsm(3, 5, 59, 300));

type Output = NaiveTime

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<TimeDelta> for TimeDelta

type Output = TimeDelta

The resulting type after applying the + operator.

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

Performs the + operation.

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

fn add_assign(&mut self, rhs: TimeDelta)

Performs the += operation.

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

Add-assign chrono::Duration to DateTime.

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

Panics if the resulting date would be out of range. Consider using DateTime<Tz>::checked_add_signed to get an Option instead.

fn add_assign(&mut self, rhs: TimeDelta)

Performs the += operation.

impl AddAssign<TimeDelta> for NaiveDate

Add-assign of TimeDelta to NaiveDate.

This discards the fractional days in TimeDelta, rounding to the closest integral number of days towards TimeDelta::zero().

Panics

Panics if the resulting date would be out of range. Consider using NaiveDate::checked_add_signed to get an Option instead.

fn add_assign(&mut self, rhs: TimeDelta)

Performs the += operation.

impl AddAssign<TimeDelta> for NaiveDateTime

Add-assign TimeDelta to 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

Panics if the resulting date would be out of range. Consider using NaiveDateTime::checked_add_signed to get an Option instead.

fn add_assign(&mut self, rhs: TimeDelta)

Performs the += operation.

impl AddAssign<TimeDelta> for NaiveTime

Add-assign TimeDelta to NaiveTime.

This wraps around and never overflows or underflows. In particular the addition ignores integral number of days.

fn add_assign(&mut self, rhs: TimeDelta)

Performs the += operation.

impl AddAssign<TimeDelta> for TimeDelta

fn add_assign(&mut self, rhs: TimeDelta)

Performs the += operation.

impl Clone for TimeDelta

fn clone(&self) -> TimeDelta

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TimeDelta

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

Formats the value using the given formatter.

impl Default for TimeDelta

fn default() -> TimeDelta

Returns the “default value” for a type.

impl Display for TimeDelta

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

Format a TimeDelta using the ISO 8601 format

impl Div<i32> for TimeDelta

type Output = TimeDelta

The resulting type after applying the / operator.

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

Performs the / operation.

impl Hash for TimeDelta

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 TimeDelta

type Output = TimeDelta

The resulting type after applying the * operator.

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

Performs the * operation.

impl Neg for TimeDelta

type Output = TimeDelta

The resulting type after applying the - operator.

fn neg(self) -> TimeDelta

Performs the unary - operation.

impl Ord for TimeDelta

fn cmp(&self, other: &TimeDelta) -> 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<TimeDelta> for TimeDelta

fn eq(&self, other: &TimeDelta) -> 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<TimeDelta> for TimeDelta

fn partial_cmp(&self, other: &TimeDelta) -> 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<TimeDelta> for Date<Tz>

type Output = Date<Tz>

The resulting type after applying the - operator.

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

Performs the - operation.

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

Subtract TimeDelta from DateTime.

This is the same as the addition with a negated TimeDelta.

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

Panics

Panics if the resulting date would be out of range. Consider using DateTime<Tz>::checked_sub_signed to get an Option instead.

type Output = DateTime<Tz>

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<TimeDelta> for NaiveDate

Subtract TimeDelta from NaiveDate.

This discards the fractional days in TimeDelta, rounding to the closest integral number of days towards TimeDelta::zero(). It is the same as the addition with a negated TimeDelta.

Panics

Panics if the resulting date would be out of range. Consider using NaiveDate::checked_sub_signed to get an Option instead.

Example

use chrono::{NaiveDate, TimeDelta};

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

assert_eq!(from_ymd(2014, 1, 1) - TimeDelta::zero(), from_ymd(2014, 1, 1));
assert_eq!(from_ymd(2014, 1, 1) - TimeDelta::try_seconds(86399).unwrap(), from_ymd(2014, 1, 1));
assert_eq!(
    from_ymd(2014, 1, 1) - TimeDelta::try_seconds(-86399).unwrap(),
    from_ymd(2014, 1, 1)
);
assert_eq!(from_ymd(2014, 1, 1) - TimeDelta::try_days(1).unwrap(), from_ymd(2013, 12, 31));
assert_eq!(from_ymd(2014, 1, 1) - TimeDelta::try_days(-1).unwrap(), from_ymd(2014, 1, 2));
assert_eq!(from_ymd(2014, 1, 1) - TimeDelta::try_days(364).unwrap(), from_ymd(2013, 1, 2));
assert_eq!(
    from_ymd(2014, 1, 1) - TimeDelta::try_days(365 * 4 + 1).unwrap(),
    from_ymd(2010, 1, 1)
);
assert_eq!(
    from_ymd(2014, 1, 1) - TimeDelta::try_days(365 * 400 + 97).unwrap(),
    from_ymd(1614, 1, 1)
);

type Output = NaiveDate

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<TimeDelta> for NaiveDateTime

Subtract TimeDelta from NaiveDateTime.

This is the same as the addition with a negated TimeDelta.

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

Panics if the resulting date would be out of range. Consider using NaiveDateTime::checked_sub_signed to get an Option instead.

Example

use chrono::{NaiveDate, TimeDelta};

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) - TimeDelta::zero(), hms(3, 5, 7));
assert_eq!(hms(3, 5, 7) - TimeDelta::try_seconds(1).unwrap(), hms(3, 5, 6));
assert_eq!(hms(3, 5, 7) - TimeDelta::try_seconds(-1).unwrap(), hms(3, 5, 8));
assert_eq!(hms(3, 5, 7) - TimeDelta::try_seconds(3600 + 60).unwrap(), hms(2, 4, 7));
assert_eq!(
    hms(3, 5, 7) - TimeDelta::try_seconds(86_400).unwrap(),
    from_ymd(2016, 7, 7).and_hms_opt(3, 5, 7).unwrap()
);
assert_eq!(
    hms(3, 5, 7) - TimeDelta::try_days(365).unwrap(),
    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) - TimeDelta::try_milliseconds(670).unwrap(), 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 - TimeDelta::zero(), hmsm(3, 5, 59, 1_300));
assert_eq!(leap - TimeDelta::try_milliseconds(200).unwrap(), hmsm(3, 5, 59, 1_100));
assert_eq!(leap - TimeDelta::try_milliseconds(500).unwrap(), hmsm(3, 5, 59, 800));
assert_eq!(leap - TimeDelta::try_seconds(60).unwrap(), hmsm(3, 5, 0, 300));
assert_eq!(leap - TimeDelta::try_days(1).unwrap(),
           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: TimeDelta) -> NaiveDateTime

Performs the - operation.

impl Sub<TimeDelta> for NaiveTime

Subtract TimeDelta from NaiveTime.

This wraps around and never overflows or underflows. In particular the subtraction ignores integral number of days. This is the same as addition with a negated TimeDelta.

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::{NaiveTime, TimeDelta};

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) - TimeDelta::zero(), from_hmsm(3, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) - TimeDelta::try_seconds(1).unwrap(), from_hmsm(3, 5, 6, 0));
assert_eq!(
    from_hmsm(3, 5, 7, 0) - TimeDelta::try_seconds(60 + 5).unwrap(),
    from_hmsm(3, 4, 2, 0)
);
assert_eq!(
    from_hmsm(3, 5, 7, 0) - TimeDelta::try_seconds(2 * 60 * 60 + 6 * 60).unwrap(),
    from_hmsm(0, 59, 7, 0)
);
assert_eq!(
    from_hmsm(3, 5, 7, 0) - TimeDelta::try_milliseconds(80).unwrap(),
    from_hmsm(3, 5, 6, 920)
);
assert_eq!(
    from_hmsm(3, 5, 7, 950) - TimeDelta::try_milliseconds(280).unwrap(),
    from_hmsm(3, 5, 7, 670)
);

The subtraction wraps around.

assert_eq!(from_hmsm(3, 5, 7, 0) - TimeDelta::try_seconds(8*60*60).unwrap(), from_hmsm(19, 5, 7, 0));
assert_eq!(from_hmsm(3, 5, 7, 0) - TimeDelta::try_days(800).unwrap(), 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 - TimeDelta::zero(), from_hmsm(3, 5, 59, 1_300));
assert_eq!(leap - TimeDelta::try_milliseconds(200).unwrap(), from_hmsm(3, 5, 59, 1_100));
assert_eq!(leap - TimeDelta::try_milliseconds(500).unwrap(), from_hmsm(3, 5, 59, 800));
assert_eq!(leap - TimeDelta::try_seconds(60).unwrap(), from_hmsm(3, 5, 0, 300));
assert_eq!(leap - TimeDelta::try_days(1).unwrap(), from_hmsm(3, 6, 0, 300));

type Output = NaiveTime

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<TimeDelta> for TimeDelta

type Output = TimeDelta

The resulting type after applying the - operator.

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

Performs the - operation.

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

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

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

Subtract-assign TimeDelta from DateTime.

This is the same as the addition with a negated TimeDelta.

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

Panics

Panics if the resulting date would be out of range. Consider using DateTime<Tz>::checked_sub_signed to get an Option instead.

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

impl SubAssign<TimeDelta> for NaiveDate

Subtract-assign TimeDelta from NaiveDate.

This discards the fractional days in TimeDelta, rounding to the closest integral number of days towards TimeDelta::zero(). It is the same as the addition with a negated TimeDelta.

Panics

Panics if the resulting date would be out of range. Consider using NaiveDate::checked_sub_signed to get an Option instead.

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

impl SubAssign<TimeDelta> for NaiveDateTime

Subtract-assign TimeDelta from NaiveDateTime.

This is the same as the addition with a negated TimeDelta.

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

Panics if the resulting date would be out of range. Consider using NaiveDateTime::checked_sub_signed to get an Option instead.

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

impl SubAssign<TimeDelta> for NaiveTime

Subtract-assign TimeDelta from NaiveTime.

This wraps around and never overflows or underflows. In particular the subtraction ignores integral number of days.

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

impl SubAssign<TimeDelta> for TimeDelta

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

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

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

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

impl Sum<TimeDelta> for TimeDelta

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

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

impl Copy for TimeDelta

impl Eq for TimeDelta

impl StructuralEq for TimeDelta

impl StructuralPartialEq for TimeDelta