Struct chrono::naive::NaiveDateTime

pub struct NaiveDateTime { /* private fields */ }

ISO 8601 combined date and time without timezone.

Example

NaiveDateTime is commonly created from NaiveDate.

use chrono::{NaiveDate, NaiveDateTime};

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

You can use typical date-like and time-like methods, provided that relevant traits are in the scope.

use chrono::{Datelike, Timelike, Weekday};

assert_eq!(dt.weekday(), Weekday::Fri);
assert_eq!(dt.num_seconds_from_midnight(), 33011);

Implementations

impl NaiveDateTime

pub const fn new(date: NaiveDate, time: NaiveTime) -> NaiveDateTime

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, NaiveTime, NaiveDateTime};

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

pub fn from_timestamp(secs: i64, nsecs: u32) -> NaiveDateTime

👎Deprecated since 0.4.23: use from_timestamp_opt() instead

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 the leap second. (The true “UNIX timestamp” cannot represent a leap second unambiguously.)

Panics on the out-of-range number of seconds and/or invalid nanosecond.

pub fn from_timestamp_millis(millis: i64) -> Option<NaiveDateTime>

Creates a new NaiveDateTime from milliseconds since the UNIX epoch.

The UNIX epoch starts on midnight, January 1, 1970, UTC.

Returns None on an out-of-range number of milliseconds.

Example

use chrono::NaiveDateTime;
let timestamp_millis: i64 = 1662921288000; //Sunday, September 11, 2022 6:34:48 PM
let naive_datetime = NaiveDateTime::from_timestamp_millis(timestamp_millis);
assert!(naive_datetime.is_some());
assert_eq!(timestamp_millis, naive_datetime.unwrap().timestamp_millis());

// Negative timestamps (before the UNIX epoch) are supported as well.
let timestamp_millis: i64 = -2208936075000; //Mon Jan 01 1900 14:38:45 GMT+0000
let naive_datetime = NaiveDateTime::from_timestamp_millis(timestamp_millis);
assert!(naive_datetime.is_some());
assert_eq!(timestamp_millis, naive_datetime.unwrap().timestamp_millis());

pub fn from_timestamp_micros(micros: i64) -> Option<NaiveDateTime>

Creates a new NaiveDateTime from microseconds since the UNIX epoch.

The UNIX epoch starts on midnight, January 1, 1970, UTC.

Returns None on an out-of-range number of microseconds.

Example

use chrono::NaiveDateTime;
let timestamp_micros: i64 = 1662921288000000; //Sunday, September 11, 2022 6:34:48 PM
let naive_datetime = NaiveDateTime::from_timestamp_micros(timestamp_micros);
assert!(naive_datetime.is_some());
assert_eq!(timestamp_micros, naive_datetime.unwrap().timestamp_micros());

// Negative timestamps (before the UNIX epoch) are supported as well.
let timestamp_micros: i64 = -2208936075000000; //Mon Jan 01 1900 14:38:45 GMT+0000
let naive_datetime = NaiveDateTime::from_timestamp_micros(timestamp_micros);
assert!(naive_datetime.is_some());
assert_eq!(timestamp_micros, naive_datetime.unwrap().timestamp_micros());

pub fn from_timestamp_opt(secs: i64, nsecs: u32) -> Option<NaiveDateTime>

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.

The nanosecond part can exceed 1,000,000,000 in order to represent the leap second. (The true “UNIX timestamp” cannot represent a leap second unambiguously.)

Returns None on the out-of-range number of seconds (more than 262 000 years away from common era) and/or invalid nanosecond (2 seconds or more).

Example

use chrono::{NaiveDateTime, NaiveDate};
use std::i64;

let from_timestamp_opt = NaiveDateTime::from_timestamp_opt;

assert!(from_timestamp_opt(0, 0).is_some());
assert!(from_timestamp_opt(0, 999_999_999).is_some());
assert!(from_timestamp_opt(0, 1_500_000_000).is_some()); // leap second
assert!(from_timestamp_opt(0, 2_000_000_000).is_none());
assert!(from_timestamp_opt(i64::MAX, 0).is_none());

pub fn parse_from_str(s: &str, fmt: &str) -> ParseResult<NaiveDateTime>

Parses a string with the specified format string and returns a new NaiveDateTime. See the format::strftime module on the supported escape sequences.

Example

use chrono::{NaiveDateTime, NaiveDate};

let parse_from_str = NaiveDateTime::parse_from_str;

assert_eq!(parse_from_str("2015-09-05 23:56:04", "%Y-%m-%d %H:%M:%S"),
           Ok(NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap()));
assert_eq!(parse_from_str("5sep2015pm012345.6789", "%d%b%Y%p%I%M%S%.f"),
           Ok(NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_micro_opt(13, 23, 45, 678_900).unwrap()));

Offset is ignored for the purpose of parsing.

assert_eq!(parse_from_str("2014-5-17T12:34:56+09:30", "%Y-%m-%dT%H:%M:%S%z"),
           Ok(NaiveDate::from_ymd_opt(2014, 5, 17).unwrap().and_hms_opt(12, 34, 56).unwrap()));

Leap seconds are correctly handled by treating any time of the form hh:mm:60 as a leap second. (This equally applies to the formatting, so the round trip is possible.)

assert_eq!(parse_from_str("2015-07-01 08:59:60.123", "%Y-%m-%d %H:%M:%S%.f"),
           Ok(NaiveDate::from_ymd_opt(2015, 7, 1).unwrap().and_hms_milli_opt(8, 59, 59, 1_123).unwrap()));

Missing seconds are assumed to be zero, but out-of-bound times or insufficient fields are errors otherwise.

assert_eq!(parse_from_str("94/9/4 7:15", "%y/%m/%d %H:%M"),
           Ok(NaiveDate::from_ymd_opt(1994, 9, 4).unwrap().and_hms_opt(7, 15, 0).unwrap()));

assert!(parse_from_str("04m33s", "%Mm%Ss").is_err());
assert!(parse_from_str("94/9/4 12", "%y/%m/%d %H").is_err());
assert!(parse_from_str("94/9/4 17:60", "%y/%m/%d %H:%M").is_err());
assert!(parse_from_str("94/9/4 24:00:00", "%y/%m/%d %H:%M:%S").is_err());

All parsed fields should be consistent to each other, otherwise it’s an error.

let fmt = "%Y-%m-%d %H:%M:%S = UNIX timestamp %s";
assert!(parse_from_str("2001-09-09 01:46:39 = UNIX timestamp 999999999", fmt).is_ok());
assert!(parse_from_str("1970-01-01 00:00:00 = UNIX timestamp 1", fmt).is_err());

Years before 1 BCE or after 9999 CE, require an initial sign

 let fmt = "%Y-%m-%d %H:%M:%S";
 assert!(parse_from_str("10000-09-09 01:46:39", fmt).is_err());
 assert!(parse_from_str("+10000-09-09 01:46:39", fmt).is_ok());

pub const fn date(&self) -> NaiveDate

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

pub const fn time(&self) -> NaiveTime

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

pub fn timestamp(&self) -> i64

Returns the number of non-leap seconds since the midnight on January 1, 1970.

Note that this does not account for the timezone! The true “UNIX timestamp” would count seconds since the midnight UTC on the epoch.

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(1970, 1, 1).unwrap().and_hms_milli_opt(0, 0, 1, 980).unwrap();
assert_eq!(dt.timestamp(), 1);

let dt = NaiveDate::from_ymd_opt(2001, 9, 9).unwrap().and_hms_opt(1, 46, 40).unwrap();
assert_eq!(dt.timestamp(), 1_000_000_000);

let dt = NaiveDate::from_ymd_opt(1969, 12, 31).unwrap().and_hms_opt(23, 59, 59).unwrap();
assert_eq!(dt.timestamp(), -1);

let dt = NaiveDate::from_ymd_opt(-1, 1, 1).unwrap().and_hms_opt(0, 0, 0).unwrap();
assert_eq!(dt.timestamp(), -62198755200);

pub fn timestamp_millis(&self) -> i64

Returns the number of non-leap milliseconds since midnight on January 1, 1970.

Note that this does not account for the timezone! The true “UNIX timestamp” would count seconds since the midnight UTC on the epoch.

Note also that this does reduce the number of years that can be represented from ~584 Billion to ~584 Million. (If this is a problem, please file an issue to let me know what domain needs millisecond precision over billions of years, I’m curious.)

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(1970, 1, 1).unwrap().and_hms_milli_opt(0, 0, 1, 444).unwrap();
assert_eq!(dt.timestamp_millis(), 1_444);

let dt = NaiveDate::from_ymd_opt(2001, 9, 9).unwrap().and_hms_milli_opt(1, 46, 40, 555).unwrap();
assert_eq!(dt.timestamp_millis(), 1_000_000_000_555);

let dt = NaiveDate::from_ymd_opt(1969, 12, 31).unwrap().and_hms_milli_opt(23, 59, 59, 100).unwrap();
assert_eq!(dt.timestamp_millis(), -900);

pub fn timestamp_micros(&self) -> i64

Returns the number of non-leap microseconds since midnight on January 1, 1970.

Note that this does not account for the timezone! The true “UNIX timestamp” would count seconds since the midnight UTC on the epoch.

Note also that this does reduce the number of years that can be represented from ~584 Billion to ~584 Thousand. (If this is a problem, please file an issue to let me know what domain needs microsecond precision over millennia, I’m curious.)

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(1970, 1, 1).unwrap().and_hms_micro_opt(0, 0, 1, 444).unwrap();
assert_eq!(dt.timestamp_micros(), 1_000_444);

let dt = NaiveDate::from_ymd_opt(2001, 9, 9).unwrap().and_hms_micro_opt(1, 46, 40, 555).unwrap();
assert_eq!(dt.timestamp_micros(), 1_000_000_000_000_555);

pub fn timestamp_nanos(&self) -> i64

Returns the number of non-leap nanoseconds since midnight on January 1, 1970.

Note that this does not account for the timezone! The true “UNIX timestamp” would count seconds since the midnight UTC on the epoch.

Panics

Note also that this does reduce the number of years that can be represented from ~584 Billion to ~584 years. The dates that can be represented as nanoseconds are between 1677-09-21T00:12:44.0 and 2262-04-11T23:47:16.854775804.

(If this is a problem, please file an issue to let me know what domain needs nanosecond precision over millennia, I’m curious.)

Example

use chrono::{NaiveDate, NaiveDateTime};

let dt = NaiveDate::from_ymd_opt(1970, 1, 1).unwrap().and_hms_nano_opt(0, 0, 1, 444).unwrap();
assert_eq!(dt.timestamp_nanos(), 1_000_000_444);

let dt = NaiveDate::from_ymd_opt(2001, 9, 9).unwrap().and_hms_nano_opt(1, 46, 40, 555).unwrap();

const A_BILLION: i64 = 1_000_000_000;
let nanos = dt.timestamp_nanos();
assert_eq!(nanos, 1_000_000_000_000_000_555);
assert_eq!(
    dt,
    NaiveDateTime::from_timestamp(nanos / A_BILLION, (nanos % A_BILLION) as u32)
);

pub fn timestamp_subsec_millis(&self) -> u32

Returns the number of milliseconds since the last whole non-leap second.

The return value ranges from 0 to 999, or for leap seconds, to 1,999.

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2016, 7, 8).unwrap().and_hms_nano_opt(9, 10, 11, 123_456_789).unwrap();
assert_eq!(dt.timestamp_subsec_millis(), 123);

let dt = NaiveDate::from_ymd_opt(2015, 7, 1).unwrap().and_hms_nano_opt(8, 59, 59, 1_234_567_890).unwrap();
assert_eq!(dt.timestamp_subsec_millis(), 1_234);

pub fn timestamp_subsec_micros(&self) -> u32

Returns the number of microseconds since the last whole non-leap second.

The return value ranges from 0 to 999,999, or for leap seconds, to 1,999,999.

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2016, 7, 8).unwrap().and_hms_nano_opt(9, 10, 11, 123_456_789).unwrap();
assert_eq!(dt.timestamp_subsec_micros(), 123_456);

let dt = NaiveDate::from_ymd_opt(2015, 7, 1).unwrap().and_hms_nano_opt(8, 59, 59, 1_234_567_890).unwrap();
assert_eq!(dt.timestamp_subsec_micros(), 1_234_567);

pub fn timestamp_subsec_nanos(&self) -> u32

Returns the number of nanoseconds since the last whole non-leap second.

The return value ranges from 0 to 999,999,999, or for leap seconds, to 1,999,999,999.

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2016, 7, 8).unwrap().and_hms_nano_opt(9, 10, 11, 123_456_789).unwrap();
assert_eq!(dt.timestamp_subsec_nanos(), 123_456_789);

let dt = NaiveDate::from_ymd_opt(2015, 7, 1).unwrap().and_hms_nano_opt(8, 59, 59, 1_234_567_890).unwrap();
assert_eq!(dt.timestamp_subsec_nanos(), 1_234_567_890);

pub fn checked_add_signed(self, rhs: OldDuration) -> Option<NaiveDateTime>

Adds given Duration 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.

Returns None when it will result in overflow.

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).checked_add_signed(Duration::zero()),
           Some(hms(3, 5, 7)));
assert_eq!(hms(3, 5, 7).checked_add_signed(Duration::seconds(1)),
           Some(hms(3, 5, 8)));
assert_eq!(hms(3, 5, 7).checked_add_signed(Duration::seconds(-1)),
           Some(hms(3, 5, 6)));
assert_eq!(hms(3, 5, 7).checked_add_signed(Duration::seconds(3600 + 60)),
           Some(hms(4, 6, 7)));
assert_eq!(hms(3, 5, 7).checked_add_signed(Duration::seconds(86_400)),
           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(Duration::milliseconds(450)),
           Some(hmsm(3, 5, 8, 430)));

Overflow returns None.

assert_eq!(hms(3, 5, 7).checked_add_signed(Duration::days(1_000_000_000)), None);

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.checked_add_signed(Duration::zero()),
           Some(hmsm(3, 5, 59, 1_300)));
assert_eq!(leap.checked_add_signed(Duration::milliseconds(-500)),
           Some(hmsm(3, 5, 59, 800)));
assert_eq!(leap.checked_add_signed(Duration::milliseconds(500)),
           Some(hmsm(3, 5, 59, 1_800)));
assert_eq!(leap.checked_add_signed(Duration::milliseconds(800)),
           Some(hmsm(3, 6, 0, 100)));
assert_eq!(leap.checked_add_signed(Duration::seconds(10)),
           Some(hmsm(3, 6, 9, 300)));
assert_eq!(leap.checked_add_signed(Duration::seconds(-10)),
           Some(hmsm(3, 5, 50, 300)));
assert_eq!(leap.checked_add_signed(Duration::days(1)),
           Some(from_ymd(2016, 7, 9).and_hms_milli_opt(3, 5, 59, 300).unwrap()));

pub fn checked_add_months(self, rhs: Months) -> Option<NaiveDateTime>

Adds given Months to the current date and time.

Returns None when it will result in overflow.

Overflow returns None.

Example

use std::str::FromStr;
use chrono::{Months, NaiveDate, NaiveDateTime};

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

pub fn checked_sub_signed(self, rhs: OldDuration) -> Option<NaiveDateTime>

Subtracts given Duration 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.

Returns None when it will result in overflow.

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).checked_sub_signed(Duration::zero()),
           Some(hms(3, 5, 7)));
assert_eq!(hms(3, 5, 7).checked_sub_signed(Duration::seconds(1)),
           Some(hms(3, 5, 6)));
assert_eq!(hms(3, 5, 7).checked_sub_signed(Duration::seconds(-1)),
           Some(hms(3, 5, 8)));
assert_eq!(hms(3, 5, 7).checked_sub_signed(Duration::seconds(3600 + 60)),
           Some(hms(2, 4, 7)));
assert_eq!(hms(3, 5, 7).checked_sub_signed(Duration::seconds(86_400)),
           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(Duration::milliseconds(670)),
           Some(hmsm(3, 5, 6, 780)));

Overflow returns None.

assert_eq!(hms(3, 5, 7).checked_sub_signed(Duration::days(1_000_000_000)), None);

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.checked_sub_signed(Duration::zero()),
           Some(hmsm(3, 5, 59, 1_300)));
assert_eq!(leap.checked_sub_signed(Duration::milliseconds(200)),
           Some(hmsm(3, 5, 59, 1_100)));
assert_eq!(leap.checked_sub_signed(Duration::milliseconds(500)),
           Some(hmsm(3, 5, 59, 800)));
assert_eq!(leap.checked_sub_signed(Duration::seconds(60)),
           Some(hmsm(3, 5, 0, 300)));
assert_eq!(leap.checked_sub_signed(Duration::days(1)),
           Some(from_ymd(2016, 7, 7).and_hms_milli_opt(3, 6, 0, 300).unwrap()));

pub fn checked_sub_months(self, rhs: Months) -> Option<NaiveDateTime>

Subtracts given Months from the current date and time.

Returns None when it will result in overflow.

Overflow returns None.

Example

use std::str::FromStr;
use chrono::{Months, NaiveDate, NaiveDateTime};

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

pub fn checked_add_days(self, days: Days) -> Option<Self>

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

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

pub fn checked_sub_days(self, days: Days) -> Option<Self>

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

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

pub fn signed_duration_since(self, rhs: NaiveDateTime) -> OldDuration

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::{Duration, NaiveDate};

let from_ymd = NaiveDate::from_ymd;

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()),
           Duration::seconds(3600 + 60 + 1));

// 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()),
           Duration::seconds(189 * 86_400 + 7 * 60 + 6) + Duration::milliseconds(500));

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

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()),
           Duration::seconds(3600) + Duration::milliseconds(500));
assert_eq!(from_ymd(2015, 7, 1).and_hms_opt(1, 0, 0).unwrap().signed_duration_since(leap),
           Duration::seconds(3600) - Duration::milliseconds(500));

pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>where I: Iterator<Item = B> + Clone, B: Borrow<Item<'a>>,

Formats the combined date and time with the specified formatting items. Otherwise it is the same as the ordinary format method.

The Iterator of items should be Cloneable, since the resulting DelayedFormat value may be formatted multiple times.

Example

use chrono::NaiveDate;
use chrono::format::strftime::StrftimeItems;

let fmt = StrftimeItems::new("%Y-%m-%d %H:%M:%S");
let dt = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap();
assert_eq!(dt.format_with_items(fmt.clone()).to_string(), "2015-09-05 23:56:04");
assert_eq!(dt.format("%Y-%m-%d %H:%M:%S").to_string(),    "2015-09-05 23:56:04");

The resulting DelayedFormat can be formatted directly via the Display trait.

assert_eq!(format!("{}", dt.format_with_items(fmt)), "2015-09-05 23:56:04");

pub fn format<'a>(&self, fmt: &'a str) -> DelayedFormat<StrftimeItems<'a>>

Formats the combined date and time with the specified format string. See the format::strftime module on the supported escape sequences.

This returns a DelayedFormat, which gets converted to a string only when actual formatting happens. You may use the to_string method to get a String, or just feed it into print! and other formatting macros. (In this way it avoids the redundant memory allocation.)

A wrong format string does not issue an error immediately. Rather, converting or formatting the DelayedFormat fails. You are recommended to immediately use DelayedFormat for this reason.

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap();
assert_eq!(dt.format("%Y-%m-%d %H:%M:%S").to_string(), "2015-09-05 23:56:04");
assert_eq!(dt.format("around %l %p on %b %-d").to_string(), "around 11 PM on Sep 5");

The resulting DelayedFormat can be formatted directly via the Display trait.

assert_eq!(format!("{}", dt.format("%Y-%m-%d %H:%M:%S")), "2015-09-05 23:56:04");
assert_eq!(format!("{}", dt.format("around %l %p on %b %-d")), "around 11 PM on Sep 5");

pub fn and_local_timezone<Tz: TimeZone>( &self, tz: Tz ) -> LocalResult<DateTime<Tz>>

Converts the NaiveDateTime into the timezone-aware DateTime<Tz> with the provided timezone, if possible.

This can fail in cases where the local time represented by the NaiveDateTime is not a valid local timestamp in the target timezone due to an offset transition for example if the target timezone had a change from +00:00 to +01:00 occuring at 2015-09-05 22:59:59, then a local time of 2015-09-05 23:56:04 could never occur. Similarly, if the offset transitioned in the opposite direction then there would be two local times of 2015-09-05 23:56:04, one at +00:00 and one at +01:00.

Example

use chrono::{NaiveDate, Utc};
let dt = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap().and_local_timezone(Utc).unwrap();
assert_eq!(dt.timezone(), Utc);

pub const MIN: Self = _

The minimum possible NaiveDateTime.

pub const MAX: Self = _

The maximum possible NaiveDateTime.

Trait Implementations

impl Add<Days> for NaiveDateTime

type Output = NaiveDateTime

The resulting type after applying the + operator.

fn add(self, days: Days) -> Self::Output

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<FixedOffset> for NaiveDateTime

type Output = NaiveDateTime

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Months> for NaiveDateTime

fn add(self, rhs: Months) -> Self::Output

An addition of months to NaiveDateTime clamped to valid days in resulting month.

Panics

Panics if the resulting date would be out of range.

Example

use chrono::{Duration, NaiveDateTime, Months, NaiveDate};
use std::str::FromStr;

assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 1).unwrap().and_hms_opt(1, 0, 0).unwrap() + Months::new(1),
    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(0, 2, 0).unwrap() + Months::new(11),
    NaiveDate::from_ymd_opt(2014, 12, 1).unwrap().and_hms_opt(0, 2, 0).unwrap()
);
assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 1).unwrap().and_hms_opt(0, 0, 3).unwrap() + Months::new(12),
    NaiveDate::from_ymd_opt(2015, 1, 1).unwrap().and_hms_opt(0, 0, 3).unwrap()
);
assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 1).unwrap().and_hms_opt(0, 0, 4).unwrap() + Months::new(13),
    NaiveDate::from_ymd_opt(2015, 2, 1).unwrap().and_hms_opt(0, 0, 4).unwrap()
);
assert_eq!(
    NaiveDate::from_ymd_opt(2014, 1, 31).unwrap().and_hms_opt(0, 5, 0).unwrap() + Months::new(1),
    NaiveDate::from_ymd_opt(2014, 2, 28).unwrap().and_hms_opt(0, 5, 0).unwrap()
);
assert_eq!(
    NaiveDate::from_ymd_opt(2020, 1, 31).unwrap().and_hms_opt(6, 0, 0).unwrap() + Months::new(1),
    NaiveDate::from_ymd_opt(2020, 2, 29).unwrap().and_hms_opt(6, 0, 0).unwrap()
);

type Output = NaiveDateTime

The resulting type after applying the + operator.

impl AddAssign<Duration> for NaiveDateTime

fn add_assign(&mut self, rhs: OldDuration)

Performs the += operation.

impl Clone for NaiveDateTime

fn clone(&self) -> NaiveDateTime

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Datelike for NaiveDateTime

fn year(&self) -> i32

Returns the year number in the calendar date.

See also the NaiveDate::year method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.year(), 2015);

fn month(&self) -> u32

Returns the month number starting from 1.

The return value ranges from 1 to 12.

See also the NaiveDate::month method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.month(), 9);

fn month0(&self) -> u32

Returns the month number starting from 0.

The return value ranges from 0 to 11.

See also the NaiveDate::month0 method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.month0(), 8);

fn day(&self) -> u32

Returns the day of month starting from 1.

The return value ranges from 1 to 31. (The last day of month differs by months.)

See also the NaiveDate::day method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.day(), 25);

fn day0(&self) -> u32

Returns the day of month starting from 0.

The return value ranges from 0 to 30. (The last day of month differs by months.)

See also the NaiveDate::day0 method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.day0(), 24);

fn ordinal(&self) -> u32

Returns the day of year starting from 1.

The return value ranges from 1 to 366. (The last day of year differs by years.)

See also the NaiveDate::ordinal method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.ordinal(), 268);

fn ordinal0(&self) -> u32

Returns the day of year starting from 0.

The return value ranges from 0 to 365. (The last day of year differs by years.)

See also the NaiveDate::ordinal0 method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.ordinal0(), 267);

fn weekday(&self) -> Weekday

Returns the day of week.

See also the NaiveDate::weekday method.

Example

use chrono::{NaiveDate, NaiveDateTime, Datelike, Weekday};

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.weekday(), Weekday::Fri);

fn with_year(&self, year: i32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the year number changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveDate::with_year method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_year(2016), Some(NaiveDate::from_ymd_opt(2016, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_year(-308), Some(NaiveDate::from_ymd_opt(-308, 9, 25).unwrap().and_hms_opt(12, 34, 56).unwrap()));

fn with_month(&self, month: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the month number (starting from 1) changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveDate::with_month method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 30).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_month(10), Some(NaiveDate::from_ymd_opt(2015, 10, 30).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_month(13), None); // no month 13
assert_eq!(dt.with_month(2), None); // no February 30

fn with_month0(&self, month0: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the month number (starting from 0) changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveDate::with_month0 method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 30).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_month0(9), Some(NaiveDate::from_ymd_opt(2015, 10, 30).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_month0(12), None); // no month 13
assert_eq!(dt.with_month0(1), None); // no February 30

fn with_day(&self, day: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the day of month (starting from 1) changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveDate::with_day method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_day(30), Some(NaiveDate::from_ymd_opt(2015, 9, 30).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_day(31), None); // no September 31

fn with_day0(&self, day0: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the day of month (starting from 0) changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveDate::with_day0 method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_day0(29), Some(NaiveDate::from_ymd_opt(2015, 9, 30).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_day0(30), None); // no September 31

fn with_ordinal(&self, ordinal: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the day of year (starting from 1) changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveDate::with_ordinal method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_ordinal(60),
           Some(NaiveDate::from_ymd_opt(2015, 3, 1).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_ordinal(366), None); // 2015 had only 365 days

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2016, 9, 8).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_ordinal(60),
           Some(NaiveDate::from_ymd_opt(2016, 2, 29).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_ordinal(366),
           Some(NaiveDate::from_ymd_opt(2016, 12, 31).unwrap().and_hms_opt(12, 34, 56).unwrap()));

fn with_ordinal0(&self, ordinal0: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the day of year (starting from 0) changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveDate::with_ordinal0 method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_ordinal0(59),
           Some(NaiveDate::from_ymd_opt(2015, 3, 1).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_ordinal0(365), None); // 2015 had only 365 days

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2016, 9, 8).unwrap().and_hms_opt(12, 34, 56).unwrap();
assert_eq!(dt.with_ordinal0(59),
           Some(NaiveDate::from_ymd_opt(2016, 2, 29).unwrap().and_hms_opt(12, 34, 56).unwrap()));
assert_eq!(dt.with_ordinal0(365),
           Some(NaiveDate::from_ymd_opt(2016, 12, 31).unwrap().and_hms_opt(12, 34, 56).unwrap()));

fn iso_week(&self) -> IsoWeek

Returns the ISO week.

fn year_ce(&self) -> (bool, u32)

Returns the absolute year number starting from 1 with a boolean flag, which is false when the year predates the epoch (BCE/BC) and true otherwise (CE/AD).

fn num_days_from_ce(&self) -> i32

Counts the days in the proleptic Gregorian calendar, with January 1, Year 1 (CE) as day 1.

impl Debug for NaiveDateTime

The Debug output of the naive date and time dt is the same as dt.format("%Y-%m-%dT%H:%M:%S%.f").

The string printed can be readily parsed via the parse method on str.

It should be noted that, for leap seconds not on the minute boundary, it may print a representation not distinguishable from non-leap seconds. This doesn’t matter in practice, since such leap seconds never happened. (By the time of the first leap second on 1972-06-30, every time zone offset around the world has standardized to the 5-minute alignment.)

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2016, 11, 15).unwrap().and_hms_opt(7, 39, 24).unwrap();
assert_eq!(format!("{:?}", dt), "2016-11-15T07:39:24");

Leap seconds may also be used.

let dt = NaiveDate::from_ymd_opt(2015, 6, 30).unwrap().and_hms_milli_opt(23, 59, 59, 1_500).unwrap();
assert_eq!(format!("{:?}", dt), "2015-06-30T23:59:60.500");

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

Formats the value using the given formatter.

impl Default for NaiveDateTime

The default value for a NaiveDateTime is one with epoch 0 that is, 1st of January 1970 at 00:00:00.

Example

use chrono::NaiveDateTime;

let default_date = NaiveDateTime::default();
assert_eq!(default_date, NaiveDateTime::from_timestamp(0, 0));

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for NaiveDateTime

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for NaiveDateTime

The Display output of the naive date and time dt is the same as dt.format("%Y-%m-%d %H:%M:%S%.f").

It should be noted that, for leap seconds not on the minute boundary, it may print a representation not distinguishable from non-leap seconds. This doesn’t matter in practice, since such leap seconds never happened. (By the time of the first leap second on 1972-06-30, every time zone offset around the world has standardized to the 5-minute alignment.)

Example

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2016, 11, 15).unwrap().and_hms_opt(7, 39, 24).unwrap();
assert_eq!(format!("{}", dt), "2016-11-15 07:39:24");

Leap seconds may also be used.

let dt = NaiveDate::from_ymd_opt(2015, 6, 30).unwrap().and_hms_milli_opt(23, 59, 59, 1_500).unwrap();
assert_eq!(format!("{}", dt), "2015-06-30 23:59:60.500");

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

Formats the value using the given formatter.

impl DurationRound for NaiveDateTime

type Err = RoundingError

Error that can occur in rounding or truncating

fn duration_round(self, duration: Duration) -> Result<Self, Self::Err>

Return a copy rounded by Duration.

fn duration_trunc(self, duration: Duration) -> Result<Self, Self::Err>

Return a copy truncated by Duration.

impl FromStr for NaiveDateTime

Parsing a str into a NaiveDateTime uses the same format, %Y-%m-%dT%H:%M:%S%.f, as in Debug.

Example

use chrono::{NaiveDateTime, NaiveDate};

let dt = NaiveDate::from_ymd_opt(2015, 9, 18).unwrap().and_hms_opt(23, 56, 4).unwrap();
assert_eq!("2015-09-18T23:56:04".parse::<NaiveDateTime>(), Ok(dt));

let dt = NaiveDate::from_ymd_opt(12345, 6, 7).unwrap().and_hms_milli_opt(7, 59, 59, 1_500).unwrap(); // leap second
assert_eq!("+12345-6-7T7:59:60.5".parse::<NaiveDateTime>(), Ok(dt));

assert!("foo".parse::<NaiveDateTime>().is_err());

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> ParseResult<NaiveDateTime>

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

impl Hash for NaiveDateTime

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 Ord for NaiveDateTime

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

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

fn partial_cmp(&self, other: &NaiveDateTime) -> 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 Serialize for NaiveDateTime

Serialize a NaiveDateTime as an RFC 3339 string

See the serde module for alternate serialization formats.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>where S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<Days> for NaiveDateTime

type Output = NaiveDateTime

The resulting type after applying the - operator.

fn sub(self, days: Days) -> Self::Output

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<FixedOffset> for NaiveDateTime

type Output = NaiveDateTime

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Months> for NaiveDateTime

A subtraction of Months from NaiveDateTime clamped to valid days in resulting month.

Panics

Panics if the resulting date would be out of range.

Example

use chrono::{Duration, NaiveDateTime, Months, NaiveDate};
use std::str::FromStr;

assert_eq!(
    NaiveDate::from_ymd_opt(2014, 01, 01).unwrap().and_hms_opt(01, 00, 00).unwrap() - Months::new(11),
    NaiveDate::from_ymd_opt(2013, 02, 01).unwrap().and_hms_opt(01, 00, 00).unwrap()
);
assert_eq!(
    NaiveDate::from_ymd_opt(2014, 01, 01).unwrap().and_hms_opt(00, 02, 00).unwrap() - Months::new(12),
    NaiveDate::from_ymd_opt(2013, 01, 01).unwrap().and_hms_opt(00, 02, 00).unwrap()
);
assert_eq!(
    NaiveDate::from_ymd_opt(2014, 01, 01).unwrap().and_hms_opt(00, 00, 03).unwrap() - Months::new(13),
    NaiveDate::from_ymd_opt(2012, 12, 01).unwrap().and_hms_opt(00, 00, 03).unwrap()
);

type Output = NaiveDateTime

The resulting type after applying the - operator.

fn sub(self, rhs: Months) -> Self::Output

Performs the - operation.

impl Sub<NaiveDateTime> for NaiveDateTime

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.

The implementation is a wrapper around NaiveDateTime::signed_duration_since.

Example

use chrono::{Duration, NaiveDate};

let from_ymd = NaiveDate::from_ymd;

let d = from_ymd(2016, 7, 8);
assert_eq!(d.and_hms_opt(3, 5, 7).unwrap() - d.and_hms_opt(2, 4, 6).unwrap(), Duration::seconds(3600 + 60 + 1));

// 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() - d0.and_hms_opt(0, 0, 0).unwrap(),
           Duration::seconds(189 * 86_400 + 7 * 60 + 6) + Duration::milliseconds(500));

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

let leap = from_ymd(2015, 6, 30).and_hms_milli_opt(23, 59, 59, 1_500).unwrap();
assert_eq!(leap - from_ymd(2015, 6, 30).and_hms_opt(23, 0, 0).unwrap(),
           Duration::seconds(3600) + Duration::milliseconds(500));
assert_eq!(from_ymd(2015, 7, 1).and_hms_opt(1, 0, 0).unwrap() - leap,
           Duration::seconds(3600) - Duration::milliseconds(500));

type Output = Duration

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign<Duration> for NaiveDateTime

fn sub_assign(&mut self, rhs: OldDuration)

Performs the -= operation.

impl Timelike for NaiveDateTime

fn hour(&self) -> u32

Returns the hour number from 0 to 23.

See also the NaiveTime::hour method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.hour(), 12);

fn minute(&self) -> u32

Returns the minute number from 0 to 59.

See also the NaiveTime::minute method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.minute(), 34);

fn second(&self) -> u32

Returns the second number from 0 to 59.

See also the NaiveTime::second method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.second(), 56);

fn nanosecond(&self) -> u32

Returns the number of nanoseconds since the whole non-leap second. The range from 1,000,000,000 to 1,999,999,999 represents the leap second.

See also the NaiveTime::nanosecond method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.nanosecond(), 789_000_000);

fn with_hour(&self, hour: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the hour number changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveTime::with_hour method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.with_hour(7),
           Some(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(7, 34, 56, 789).unwrap()));
assert_eq!(dt.with_hour(24), None);

fn with_minute(&self, min: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the minute number changed.

Returns None when the resulting NaiveDateTime would be invalid.

See also the NaiveTime::with_minute method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.with_minute(45),
           Some(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 45, 56, 789).unwrap()));
assert_eq!(dt.with_minute(60), None);

fn with_second(&self, sec: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with the second number changed.

Returns None when the resulting NaiveDateTime would be invalid. As with the NaiveDateTime::second method, the input range is restricted to 0 through 59.

See also the NaiveTime::with_second method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.with_second(17),
           Some(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 17, 789).unwrap()));
assert_eq!(dt.with_second(60), None);

fn with_nanosecond(&self, nano: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime with nanoseconds since the whole non-leap second changed.

Returns None when the resulting NaiveDateTime would be invalid. As with the NaiveDateTime::nanosecond method, the input range can exceed 1,000,000,000 for leap seconds.

See also the NaiveTime::with_nanosecond method.

Example

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

let dt: NaiveDateTime = NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_milli_opt(12, 34, 56, 789).unwrap();
assert_eq!(dt.with_nanosecond(333_333_333),
           Some(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_nano_opt(12, 34, 56, 333_333_333).unwrap()));
assert_eq!(dt.with_nanosecond(1_333_333_333), // leap second
           Some(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().and_hms_nano_opt(12, 34, 56, 1_333_333_333).unwrap()));
assert_eq!(dt.with_nanosecond(2_000_000_000), None);

fn hour12(&self) -> (bool, u32)

Returns the hour number from 1 to 12 with a boolean flag, which is false for AM and true for PM.

fn num_seconds_from_midnight(&self) -> u32

Returns the number of non-leap seconds past the last midnight.

impl Copy for NaiveDateTime

impl Eq for NaiveDateTime

impl StructuralEq for NaiveDateTime

impl StructuralPartialEq for NaiveDateTime