Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

DateTimeTrait

Fully qualified path: chrono::datetime::DateTimeTrait

pub trait DateTimeTrait

Trait constants

MIN

The minimum possible NaiveDateTime.

Fully qualified path: chrono::datetime::DateTimeTrait::MIN

const MIN: DateTime;

MAX

The maximum possible NaiveDateTime.

Fully qualified path: chrono::datetime::DateTimeTrait::MAX

const MAX: DateTime;

UNIX_EPOCH

The datetime of the Unix Epoch, 1970-01-01 00:00:00.

Note that while this may look like the UNIX epoch, it is missing the time zone. The actual UNIX epoch cannot be expressed by this type, however it is available as DateTime::UNIX_EPOCH.

Fully qualified path: chrono::datetime::DateTimeTrait::UNIX_EPOCH

const UNIX_EPOCH: DateTime;

Trait functions

new

Makes a new NaiveDateTime from date and time components. Equivalent to date.and_time(time) and many other helper constructors on NaiveDate.

Example

use chrono::{NaiveDate, NaiveDateTime, NaiveTime};

let d = NaiveDate::from_ymd_opt(2015, 6, 3).unwrap();
let t = NaiveTime::from_hms_milli_opt(12, 34, 56, 789).unwrap();

let dt = NaiveDateTime::new(d, t);
assert_eq!(dt.date(), d);
assert_eq!(dt.time(), t);

Fully qualified path: chrono::datetime::DateTimeTrait::new

fn new(date: Date, time: Time) -> DateTime

from_timestamp

Makes a new NaiveDateTime corresponding to a UTC date and time, from the number of non-leap seconds since the midnight UTC on January 1, 1970 (aka “UNIX timestamp”) and the number of nanoseconds since the last whole non-leap second.

For a non-naive version of this function see TimeZone::timestamp.

The nanosecond part can exceed 1,000,000,000 in order to represent a leap second, but only when secs % 60 == 59. (The true “UNIX timestamp” cannot represent a leap second unambiguously.)

Panics

Panics if the number of seconds would be out of range for a NaiveDateTime (more than ca. 262,000 years away from common era), and panics on an invalid nanosecond (2 seconds or more).

Fully qualified path: chrono::datetime::DateTimeTrait::from_timestamp

fn from_timestamp(secs: i64) -> Option<DateTime>

from_block_timestamp

Fully qualified path: chrono::datetime::DateTimeTrait::from_block_timestamp

fn from_block_timestamp(block_timestamp: u64) -> Option<DateTime>

date

Retrieves a date component.

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2016, 7, 8).unwrap().and_hms_opt(9, 10, 11).unwrap();
assert_eq!(dt.date(), NaiveDate::from_ymd_opt(2016, 7, 8).unwrap());

Fully qualified path: chrono::datetime::DateTimeTrait::date

fn date(self: @DateTime) -> Date

time

Retrieves a time component.

Example

use chrono::{NaiveDate, NaiveTime};

let dt = NaiveDate::from_ymd_opt(2016, 7, 8).unwrap().and_hms_opt(9, 10, 11).unwrap();
assert_eq!(dt.time(), NaiveTime::from_hms_opt(9, 10, 11).unwrap());

Fully qualified path: chrono::datetime::DateTimeTrait::time

fn time(self: @DateTime) -> Time

timestamp

Returns the number of non-leap seconds since January 1, 1970 0:00:00 UTC (aka “UNIX timestamp”).

The reverse operation of creating a DateTime from a timestamp can be performed using from_timestamp or TimeZone::timestamp_opt.

use chrono::{DateTime, TimeZone, Utc};

let dt: DateTime<Utc> = Utc.with_ymd_and_hms(2015, 5, 15, 0, 0, 0).unwrap();
assert_eq!(dt.timestamp(), 1431648000);

assert_eq!(DateTime::from_timestamp(dt.timestamp(), dt.timestamp_subsec_nanos()).unwrap(),
dt);

Fully qualified path: chrono::datetime::DateTimeTrait::timestamp

fn timestamp(self: @DateTime) -> i64

checked_add_signed

Adds given TimeDelta to the current date and time.

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.

Errors

Returns None if the resulting date would be out of range.

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).checked_add_signed(TimeDelta::zero()), Some(hms(3, 5, 7)));
assert_eq!(
    hms(3, 5, 7).checked_add_signed(TimeDelta::try_seconds(1).unwrap()),
    Some(hms(3, 5, 8))
);
assert_eq!(
    hms(3, 5, 7).checked_add_signed(TimeDelta::try_seconds(-1).unwrap()),
    Some(hms(3, 5, 6))
);
assert_eq!(
    hms(3, 5, 7).checked_add_signed(TimeDelta::try_seconds(3600 + 60).unwrap()),
    Some(hms(4, 6, 7))
);
assert_eq!(
    hms(3, 5, 7).checked_add_signed(TimeDelta::try_seconds(86_400).unwrap()),
    Some(from_ymd(2016, 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, 980).checked_add_signed(TimeDelta::try_milliseconds(450).unwrap()),
    Some(hmsm(3, 5, 8, 430))
);

Overflow returns None.

 use chrono::{TimeDelta, NaiveDate};
 let hms = |h, m, s| NaiveDate::from_ymd_opt(2016, 7, 8).unwrap().and_hms_opt(h, m,
s).unwrap();
assert_eq!(hms(3, 5, 7).checked_add_signed(TimeDelta::try_days(1_000_000_000).unwrap()),
None);

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

 use chrono::{TimeDelta, NaiveDate};
 let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();
 let hmsm = |h, m, s, milli| from_ymd(2016, 7, 8).and_hms_milli_opt(h, m, s,
milli).unwrap();
let leap = hmsm(3, 5, 59, 1_300);
assert_eq!(leap.checked_add_signed(TimeDelta::zero()),
           Some(hmsm(3, 5, 59, 1_300)));
assert_eq!(leap.checked_add_signed(TimeDelta::try_milliseconds(-500).unwrap()),
           Some(hmsm(3, 5, 59, 800)));
assert_eq!(leap.checked_add_signed(TimeDelta::try_milliseconds(500).unwrap()),
           Some(hmsm(3, 5, 59, 1_800)));
assert_eq!(leap.checked_add_signed(TimeDelta::try_milliseconds(800).unwrap()),
           Some(hmsm(3, 6, 0, 100)));
assert_eq!(leap.checked_add_signed(TimeDelta::try_seconds(10).unwrap()),
           Some(hmsm(3, 6, 9, 300)));
assert_eq!(leap.checked_add_signed(TimeDelta::try_seconds(-10).unwrap()),
           Some(hmsm(3, 5, 50, 300)));
assert_eq!(leap.checked_add_signed(TimeDelta::try_days(1).unwrap()),
           Some(from_ymd(2016, 7, 9).and_hms_milli_opt(3, 5, 59, 300).unwrap()));

Fully qualified path: chrono::datetime::DateTimeTrait::checked_add_signed

fn checked_add_signed(self: @DateTime, rhs: TimeDelta) -> Option<DateTime>

checked_add_months

Adds given Months to the current date and time.

Uses the last day of the month if the day does not exist in the resulting month.

Errors

Returns None if the resulting date would be out of range.

Example

use chrono::{Months, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 1)
        .unwrap()
        .and_hms_opt(1, 0, 0)
        .unwrap()
        .checked_add_months(Months::new(1)),
    Some(NaiveDate::from_ymd_opt(2014, 2, 1).unwrap().and_hms_opt(1, 0, 0).unwrap())
);

assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 1)
        .unwrap()
        .and_hms_opt(1, 0, 0)
        .unwrap()
        .checked_add_months(Months::new(core::i32::MAX as u32 + 1)),
    None
);

Fully qualified path: chrono::datetime::DateTimeTrait::checked_add_months

fn checked_add_months(self: @DateTime, rhs: Months) -> Option<DateTime>

checked_sub_signed

Subtracts given TimeDelta from the current date and time.

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.

Errors

Returns None if the resulting date would be out of range.

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).checked_sub_signed(TimeDelta::zero()), Some(hms(3, 5, 7)));
assert_eq!(
    hms(3, 5, 7).checked_sub_signed(TimeDelta::try_seconds(1).unwrap()),
    Some(hms(3, 5, 6))
);
assert_eq!(
    hms(3, 5, 7).checked_sub_signed(TimeDelta::try_seconds(-1).unwrap()),
    Some(hms(3, 5, 8))
);
assert_eq!(
    hms(3, 5, 7).checked_sub_signed(TimeDelta::try_seconds(3600 + 60).unwrap()),
    Some(hms(2, 4, 7))
);
assert_eq!(
    hms(3, 5, 7).checked_sub_signed(TimeDelta::try_seconds(86_400).unwrap()),
    Some(from_ymd(2016, 7, 7).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).checked_sub_signed(TimeDelta::try_milliseconds(670).unwrap()),
    Some(hmsm(3, 5, 6, 780))
);

Overflow returns None.

 use chrono::{TimeDelta, NaiveDate};
 let hms = |h, m, s| NaiveDate::from_ymd_opt(2016, 7, 8).unwrap().and_hms_opt(h, m,
s).unwrap();
assert_eq!(hms(3, 5, 7).checked_sub_signed(TimeDelta::try_days(1_000_000_000).unwrap()),
None);

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

 use chrono::{TimeDelta, NaiveDate};
 let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();
 let hmsm = |h, m, s, milli| from_ymd(2016, 7, 8).and_hms_milli_opt(h, m, s,
milli).unwrap();
let leap = hmsm(3, 5, 59, 1_300);
assert_eq!(leap.checked_sub_signed(TimeDelta::zero()),
           Some(hmsm(3, 5, 59, 1_300)));
assert_eq!(leap.checked_sub_signed(TimeDelta::try_milliseconds(200).unwrap()),
           Some(hmsm(3, 5, 59, 1_100)));
assert_eq!(leap.checked_sub_signed(TimeDelta::try_milliseconds(500).unwrap()),
           Some(hmsm(3, 5, 59, 800)));
assert_eq!(leap.checked_sub_signed(TimeDelta::try_seconds(60).unwrap()),
           Some(hmsm(3, 5, 0, 300)));
assert_eq!(leap.checked_sub_signed(TimeDelta::try_days(1).unwrap()),
           Some(from_ymd(2016, 7, 7).and_hms_milli_opt(3, 6, 0, 300).unwrap()));

Fully qualified path: chrono::datetime::DateTimeTrait::checked_sub_signed

fn checked_sub_signed(self: @DateTime, rhs: TimeDelta) -> Option<DateTime>

checked_sub_months

Subtracts given Months from the current date and time.

Uses the last day of the month if the day does not exist in the resulting month.

Errors

Returns None if the resulting date would be out of range.

Example

use chrono::{Months, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 1)
        .unwrap()
        .and_hms_opt(1, 0, 0)
        .unwrap()
        .checked_sub_months(Months::new(1)),
    Some(NaiveDate::from_ymd_opt(2013, 12, 1).unwrap().and_hms_opt(1, 0, 0).unwrap())
);

assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 1)
        .unwrap()
        .and_hms_opt(1, 0, 0)
        .unwrap()
        .checked_sub_months(Months::new(core::i32::MAX as u32 + 1)),
    None
);

Fully qualified path: chrono::datetime::DateTimeTrait::checked_sub_months

fn checked_sub_months(self: @DateTime, rhs: Months) -> Option<DateTime>

checked_add_days

Add a duration in Days to the date part of the NaiveDateTime

Returns None if the resulting date would be out of range.

Fully qualified path: chrono::datetime::DateTimeTrait::checked_add_days

fn checked_add_days(self: @DateTime, days: Days) -> Option<DateTime>

checked_sub_days

Subtract a duration in Days from the date part of the NaiveDateTime

Returns None if the resulting date would be out of range.

Fully qualified path: chrono::datetime::DateTimeTrait::checked_sub_days

fn checked_sub_days(self: @DateTime, days: Days) -> Option<DateTime>

signed_duration_since

Subtracts another NaiveDateTime from the current date and time. This does not overflow or underflow at all.

As a part of Chrono’s leap second handling, the subtraction assumes that there is no leap second ever, except when any of the NaiveDateTimes themselves represents a leap second in which case the assumption becomes that there are exactly one (or two) leap second(s) ever.

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);
assert_eq!(
    d.and_hms_opt(3, 5, 7).unwrap().signed_duration_since(d.and_hms_opt(2, 4, 6).unwrap()),
    TimeDelta::try_seconds(3600 + 60 + 1).unwrap()
);

// July 8 is 190th day in the year 2016
let d0 = from_ymd(2016, 1, 1);
assert_eq!(
    d.and_hms_milli_opt(0, 7, 6, 500)
        .unwrap()
        .signed_duration_since(d0.and_hms_opt(0, 0, 0).unwrap()),
    TimeDelta::try_seconds(189 * 86_400 + 7 * 60 + 6).unwrap()
        + TimeDelta::try_milliseconds(500).unwrap()
);

Leap seconds are handled, but the subtraction assumes that there were no other leap seconds happened.

 use chrono::{TimeDelta, NaiveDate};
 let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();
let leap = from_ymd(2015, 6, 30).and_hms_milli_opt(23, 59, 59, 1_500).unwrap();
assert_eq!(
    leap.signed_duration_since(from_ymd(2015, 6, 30).and_hms_opt(23, 0, 0).unwrap()),
    TimeDelta::try_seconds(3600).unwrap() + TimeDelta::try_milliseconds(500).unwrap()
);
assert_eq!(
    from_ymd(2015, 7, 1).and_hms_opt(1, 0, 0).unwrap().signed_duration_since(leap),
    TimeDelta::try_seconds(3600).unwrap() - TimeDelta::try_milliseconds(500).unwrap()
);

Fully qualified path: chrono::datetime::DateTimeTrait::signed_duration_since

fn signed_duration_since(self: @DateTime, rhs: DateTime) -> TimeDelta