Struct NaiveDate

struct NaiveDate { ... }

ISO 8601 calendar date without timezone. Allows for every proleptic Gregorian date from Jan 1, 262145 BCE to Dec 31, 262143 CE. Also supports the conversion from ISO 8601 ordinal and week date.

Calendar Date

The ISO 8601 calendar date follows the proleptic Gregorian calendar. It is like a normal civil calendar but note some slight differences:

Week Date

The ISO 8601 week date is a triple of year number, week number and day of the week with the following rules:

Chrono's date types default to the ISO 8601 calendar date, but Datelike::iso_week and Datelike::weekday methods can be used to get the corresponding week date.

Ordinal Date

The ISO 8601 ordinal date is a pair of year number and day of the year ("ordinal"). The ordinal number ranges from 1 to 365 or 366 depending on the year. The year number is the same as that of the calendar date.

This is currently the internal format of Chrono's date types.

Implementations

impl NaiveDate

const fn from_ymd(year: i32, month: u32, day: u32) -> NaiveDate

Makes a new NaiveDate from the calendar date (year, month and day).

Panics

Panics if the specified calendar day does not exist, on invalid values for month or day, or if year is out of range for NaiveDate.

const fn from_ymd_opt(year: i32, month: u32, day: u32) -> Option<NaiveDate>

Makes a new NaiveDate from the calendar date (year, month and day).

Errors

Returns None if:

  • The specified calendar day does not exist (for example 2023-04-31).
  • The value for month or day is invalid.
  • year is out of range for NaiveDate.

Example

use chrono::NaiveDate;

let from_ymd_opt = NaiveDate::from_ymd_opt;

assert!(from_ymd_opt(2015, 3, 14).is_some());
assert!(from_ymd_opt(2015, 0, 14).is_none());
assert!(from_ymd_opt(2015, 2, 29).is_none());
assert!(from_ymd_opt(-4, 2, 29).is_some()); // 5 BCE is a leap year
assert!(from_ymd_opt(400000, 1, 1).is_none());
assert!(from_ymd_opt(-400000, 1, 1).is_none());

const fn from_yo(year: i32, ordinal: u32) -> NaiveDate

Makes a new NaiveDate from the ordinal date (year and day of the year).

Panics

Panics if the specified ordinal day does not exist, on invalid values for ordinal, or if year is out of range for NaiveDate.

const fn from_yo_opt(year: i32, ordinal: u32) -> Option<NaiveDate>

Makes a new NaiveDate from the ordinal date (year and day of the year).

Errors

Returns None if:

  • The specified ordinal day does not exist (for example 2023-366).
  • The value for ordinal is invalid (for example: 0, 400).
  • year is out of range for NaiveDate.

Example

use chrono::NaiveDate;

let from_yo_opt = NaiveDate::from_yo_opt;

assert!(from_yo_opt(2015, 100).is_some());
assert!(from_yo_opt(2015, 0).is_none());
assert!(from_yo_opt(2015, 365).is_some());
assert!(from_yo_opt(2015, 366).is_none());
assert!(from_yo_opt(-4, 366).is_some()); // 5 BCE is a leap year
assert!(from_yo_opt(400000, 1).is_none());
assert!(from_yo_opt(-400000, 1).is_none());

const fn from_isoywd(year: i32, week: u32, weekday: Weekday) -> NaiveDate

Makes a new NaiveDate from the ISO week date (year, week number and day of the week). The resulting NaiveDate may have a different year from the input year.

Panics

Panics if the specified week does not exist in that year, on invalid values for week, or if the resulting date is out of range for NaiveDate.

const fn from_isoywd_opt(year: i32, week: u32, weekday: Weekday) -> Option<NaiveDate>

Makes a new NaiveDate from the ISO week date (year, week number and day of the week). The resulting NaiveDate may have a different year from the input year.

Errors

Returns None if:

  • The specified week does not exist in that year (for example 2023 week 53).
  • The value for week is invalid (for example: 0, 60).
  • If the resulting date is out of range for NaiveDate.

Example

use chrono::{NaiveDate, Weekday};

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

assert_eq!(from_isoywd_opt(2015, 0, Weekday::Sun), None);
assert_eq!(from_isoywd_opt(2015, 10, Weekday::Sun), Some(from_ymd(2015, 3, 8)));
assert_eq!(from_isoywd_opt(2015, 30, Weekday::Mon), Some(from_ymd(2015, 7, 20)));
assert_eq!(from_isoywd_opt(2015, 60, Weekday::Mon), None);

assert_eq!(from_isoywd_opt(400000, 10, Weekday::Fri), None);
assert_eq!(from_isoywd_opt(-400000, 10, Weekday::Sat), None);

The year number of ISO week date may differ from that of the calendar date.

# use chrono::{NaiveDate, Weekday};
# let from_ymd = |y, m, d| NaiveDate::from_ymd_opt(y, m, d).unwrap();
# let from_isoywd_opt = NaiveDate::from_isoywd_opt;
//           Mo Tu We Th Fr Sa Su
// 2014-W52  22 23 24 25 26 27 28    has 4+ days of new year,
// 2015-W01  29 30 31  1  2  3  4 <- so this is the first week
assert_eq!(from_isoywd_opt(2014, 52, Weekday::Sun), Some(from_ymd(2014, 12, 28)));
assert_eq!(from_isoywd_opt(2014, 53, Weekday::Mon), None);
assert_eq!(from_isoywd_opt(2015, 1, Weekday::Mon), Some(from_ymd(2014, 12, 29)));

// 2015-W52  21 22 23 24 25 26 27    has 4+ days of old year,
// 2015-W53  28 29 30 31  1  2  3 <- so this is the last week
// 2016-W01   4  5  6  7  8  9 10
assert_eq!(from_isoywd_opt(2015, 52, Weekday::Sun), Some(from_ymd(2015, 12, 27)));
assert_eq!(from_isoywd_opt(2015, 53, Weekday::Sun), Some(from_ymd(2016, 1, 3)));
assert_eq!(from_isoywd_opt(2015, 54, Weekday::Mon), None);
assert_eq!(from_isoywd_opt(2016, 1, Weekday::Mon), Some(from_ymd(2016, 1, 4)));

const fn from_num_days_from_ce(days: i32) -> NaiveDate

Makes a new NaiveDate from a day's number in the proleptic Gregorian calendar, with January 1, 1 being day 1.

Panics

Panics if the date is out of range.

const fn from_num_days_from_ce_opt(days: i32) -> Option<NaiveDate>

Makes a new NaiveDate from a day's number in the proleptic Gregorian calendar, with January 1, 1 being day 1.

Errors

Returns None if the date is out of range.

Example

use chrono::NaiveDate;

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

assert_eq!(from_ndays_opt(730_000), Some(from_ymd(1999, 9, 3)));
assert_eq!(from_ndays_opt(1), Some(from_ymd(1, 1, 1)));
assert_eq!(from_ndays_opt(0), Some(from_ymd(0, 12, 31)));
assert_eq!(from_ndays_opt(-1), Some(from_ymd(0, 12, 30)));
assert_eq!(from_ndays_opt(100_000_000), None);
assert_eq!(from_ndays_opt(-100_000_000), None);

const fn from_weekday_of_month(year: i32, month: u32, weekday: Weekday, n: u8) -> NaiveDate

Makes a new NaiveDate by counting the number of occurrences of a particular day-of-week since the beginning of the given month. For instance, if you want the 2nd Friday of March 2017, you would use NaiveDate::from_weekday_of_month(2017, 3, Weekday::Fri, 2).

n is 1-indexed.

Panics

Panics if the specified day does not exist in that month, on invalid values for month or n, or if year is out of range for NaiveDate.

const fn from_weekday_of_month_opt(year: i32, month: u32, weekday: Weekday, n: u8) -> Option<NaiveDate>

Makes a new NaiveDate by counting the number of occurrences of a particular day-of-week since the beginning of the given month. For instance, if you want the 2nd Friday of March 2017, you would use NaiveDate::from_weekday_of_month(2017, 3, Weekday::Fri, 2).

n is 1-indexed.

Errors

Returns None if:

  • The specified day does not exist in that month (for example the 5th Monday of Apr. 2023).
  • The value for month or n is invalid.
  • year is out of range for NaiveDate.

Example

use chrono::{NaiveDate, Weekday};
assert_eq!(
    NaiveDate::from_weekday_of_month_opt(2017, 3, Weekday::Fri, 2),
    NaiveDate::from_ymd_opt(2017, 3, 10)
)

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

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

Example

use chrono::NaiveDate;

let parse_from_str = NaiveDate::parse_from_str;

assert_eq!(
    parse_from_str("2015-09-05", "%Y-%m-%d"),
    Ok(NaiveDate::from_ymd_opt(2015, 9, 5).unwrap())
);
assert_eq!(
    parse_from_str("5sep2015", "%d%b%Y"),
    Ok(NaiveDate::from_ymd_opt(2015, 9, 5).unwrap())
);

Time and offset is ignored for the purpose of parsing.

# use chrono::NaiveDate;
# let parse_from_str = NaiveDate::parse_from_str;
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())
);

Out-of-bound dates or insufficient fields are errors.

# use chrono::NaiveDate;
# let parse_from_str = NaiveDate::parse_from_str;
assert!(parse_from_str("2015/9", "%Y/%m").is_err());
assert!(parse_from_str("2015/9/31", "%Y/%m/%d").is_err());

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

# use chrono::NaiveDate;
# let parse_from_str = NaiveDate::parse_from_str;
assert!(parse_from_str("Sat, 09 Aug 2013", "%a, %d %b %Y").is_err());

fn parse_and_remainder<'a>(s: &'a str, fmt: &str) -> ParseResult<(NaiveDate, &'a str)>

Parses a string from a user-specified format into a new NaiveDate value, and a slice with the remaining portion of the string. See the format::strftime module on the supported escape sequences.

Similar to parse_from_str.

Example

# use chrono::{NaiveDate};
let (date, remainder) =
    NaiveDate::parse_and_remainder("2015-02-18 trailing text", "%Y-%m-%d").unwrap();
assert_eq!(date, NaiveDate::from_ymd_opt(2015, 2, 18).unwrap());
assert_eq!(remainder, " trailing text");

const fn checked_add_months(self: Self, months: Months) -> Option<Self>

Add a duration in Months to the date

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::{NaiveDate, Months};
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 2, 20).unwrap().checked_add_months(Months::new(6)),
    Some(NaiveDate::from_ymd_opt(2022, 8, 20).unwrap())
);
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 7, 31).unwrap().checked_add_months(Months::new(2)),
    Some(NaiveDate::from_ymd_opt(2022, 9, 30).unwrap())
);

const fn checked_sub_months(self: Self, months: Months) -> Option<Self>

Subtract a duration in Months from the date

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::{NaiveDate, Months};
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 2, 20).unwrap().checked_sub_months(Months::new(6)),
    Some(NaiveDate::from_ymd_opt(2021, 8, 20).unwrap())
);

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

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

Add a duration in Days to the date

Errors

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

Example

# use chrono::{NaiveDate, Days};
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 2, 20).unwrap().checked_add_days(Days::new(9)),
    Some(NaiveDate::from_ymd_opt(2022, 3, 1).unwrap())
);
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 7, 31).unwrap().checked_add_days(Days::new(2)),
    Some(NaiveDate::from_ymd_opt(2022, 8, 2).unwrap())
);
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 7, 31).unwrap().checked_add_days(Days::new(1000000000000)),
    None
);

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

Subtract a duration in Days from the date

Errors

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

Example

# use chrono::{NaiveDate, Days};
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 2, 20).unwrap().checked_sub_days(Days::new(6)),
    Some(NaiveDate::from_ymd_opt(2022, 2, 14).unwrap())
);
assert_eq!(
    NaiveDate::from_ymd_opt(2022, 2, 20).unwrap().checked_sub_days(Days::new(1000000000000)),
    None
);

const fn and_time(self: &Self, time: NaiveTime) -> NaiveDateTime

Makes a new NaiveDateTime from the current date and given NaiveTime.

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 = d.and_time(t);
assert_eq!(dt.date(), d);
assert_eq!(dt.time(), t);

const fn and_hms(self: &Self, hour: u32, min: u32, sec: u32) -> NaiveDateTime

Makes a new NaiveDateTime from the current date, hour, minute and second.

No leap second is allowed here; use NaiveDate::and_hms_* methods with a subsecond parameter instead.

Panics

Panics on invalid hour, minute and/or second.

const fn and_hms_opt(self: &Self, hour: u32, min: u32, sec: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime from the current date, hour, minute and second.

No leap second is allowed here; use NaiveDate::and_hms_*_opt methods with a subsecond parameter instead.

Errors

Returns None on invalid hour, minute and/or second.

Example

use chrono::NaiveDate;

let d = NaiveDate::from_ymd_opt(2015, 6, 3).unwrap();
assert!(d.and_hms_opt(12, 34, 56).is_some());
assert!(d.and_hms_opt(12, 34, 60).is_none()); // use `and_hms_milli_opt` instead
assert!(d.and_hms_opt(12, 60, 56).is_none());
assert!(d.and_hms_opt(24, 34, 56).is_none());

const fn and_hms_milli(self: &Self, hour: u32, min: u32, sec: u32, milli: u32) -> NaiveDateTime

Makes a new NaiveDateTime from the current date, hour, minute, second and millisecond.

The millisecond part is allowed to exceed 1,000,000,000 in order to represent a leap second, but only when sec == 59.

Panics

Panics on invalid hour, minute, second and/or millisecond.

const fn and_hms_milli_opt(self: &Self, hour: u32, min: u32, sec: u32, milli: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime from the current date, hour, minute, second and millisecond.

The millisecond part is allowed to exceed 1,000,000,000 in order to represent a leap second, but only when sec == 59.

Errors

Returns None on invalid hour, minute, second and/or millisecond.

Example

use chrono::NaiveDate;

let d = NaiveDate::from_ymd_opt(2015, 6, 3).unwrap();
assert!(d.and_hms_milli_opt(12, 34, 56, 789).is_some());
assert!(d.and_hms_milli_opt(12, 34, 59, 1_789).is_some()); // leap second
assert!(d.and_hms_milli_opt(12, 34, 59, 2_789).is_none());
assert!(d.and_hms_milli_opt(12, 34, 60, 789).is_none());
assert!(d.and_hms_milli_opt(12, 60, 56, 789).is_none());
assert!(d.and_hms_milli_opt(24, 34, 56, 789).is_none());

const fn and_hms_micro(self: &Self, hour: u32, min: u32, sec: u32, micro: u32) -> NaiveDateTime

Makes a new NaiveDateTime from the current date, hour, minute, second and microsecond.

The microsecond part is allowed to exceed 1,000,000,000 in order to represent a leap second, but only when sec == 59.

Panics

Panics on invalid hour, minute, second and/or microsecond.

Example

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

let d = NaiveDate::from_ymd_opt(2015, 6, 3).unwrap();

let dt: NaiveDateTime = d.and_hms_micro_opt(12, 34, 56, 789_012).unwrap();
assert_eq!(dt.year(), 2015);
assert_eq!(dt.weekday(), Weekday::Wed);
assert_eq!(dt.second(), 56);
assert_eq!(dt.nanosecond(), 789_012_000);

const fn and_hms_micro_opt(self: &Self, hour: u32, min: u32, sec: u32, micro: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime from the current date, hour, minute, second and microsecond.

The microsecond part is allowed to exceed 1,000,000 in order to represent a leap second, but only when sec == 59.

Errors

Returns None on invalid hour, minute, second and/or microsecond.

Example

use chrono::NaiveDate;

let d = NaiveDate::from_ymd_opt(2015, 6, 3).unwrap();
assert!(d.and_hms_micro_opt(12, 34, 56, 789_012).is_some());
assert!(d.and_hms_micro_opt(12, 34, 59, 1_789_012).is_some()); // leap second
assert!(d.and_hms_micro_opt(12, 34, 59, 2_789_012).is_none());
assert!(d.and_hms_micro_opt(12, 34, 60, 789_012).is_none());
assert!(d.and_hms_micro_opt(12, 60, 56, 789_012).is_none());
assert!(d.and_hms_micro_opt(24, 34, 56, 789_012).is_none());

const fn and_hms_nano(self: &Self, hour: u32, min: u32, sec: u32, nano: u32) -> NaiveDateTime

Makes a new NaiveDateTime from the current date, hour, minute, second and nanosecond.

The nanosecond part is allowed to exceed 1,000,000,000 in order to represent a leap second, but only when sec == 59.

Panics

Panics on invalid hour, minute, second and/or nanosecond.

const fn and_hms_nano_opt(self: &Self, hour: u32, min: u32, sec: u32, nano: u32) -> Option<NaiveDateTime>

Makes a new NaiveDateTime from the current date, hour, minute, second and nanosecond.

The nanosecond part is allowed to exceed 1,000,000,000 in order to represent a leap second, but only when sec == 59.

Errors

Returns None on invalid hour, minute, second and/or nanosecond.

Example

use chrono::NaiveDate;

let d = NaiveDate::from_ymd_opt(2015, 6, 3).unwrap();
assert!(d.and_hms_nano_opt(12, 34, 56, 789_012_345).is_some());
assert!(d.and_hms_nano_opt(12, 34, 59, 1_789_012_345).is_some()); // leap second
assert!(d.and_hms_nano_opt(12, 34, 59, 2_789_012_345).is_none());
assert!(d.and_hms_nano_opt(12, 34, 60, 789_012_345).is_none());
assert!(d.and_hms_nano_opt(12, 60, 56, 789_012_345).is_none());
assert!(d.and_hms_nano_opt(24, 34, 56, 789_012_345).is_none());

const fn succ(self: &Self) -> NaiveDate

Makes a new NaiveDate for the next calendar date.

Panics

Panics when self is the last representable date.

const fn succ_opt(self: &Self) -> Option<NaiveDate>

Makes a new NaiveDate for the next calendar date.

Errors

Returns None when self is the last representable date.

Example

use chrono::NaiveDate;

assert_eq!(
    NaiveDate::from_ymd_opt(2015, 6, 3).unwrap().succ_opt(),
    Some(NaiveDate::from_ymd_opt(2015, 6, 4).unwrap())
);
assert_eq!(NaiveDate::MAX.succ_opt(), None);

const fn pred(self: &Self) -> NaiveDate

Makes a new NaiveDate for the previous calendar date.

Panics

Panics when self is the first representable date.

const fn pred_opt(self: &Self) -> Option<NaiveDate>

Makes a new NaiveDate for the previous calendar date.

Errors

Returns None when self is the first representable date.

Example

use chrono::NaiveDate;

assert_eq!(
    NaiveDate::from_ymd_opt(2015, 6, 3).unwrap().pred_opt(),
    Some(NaiveDate::from_ymd_opt(2015, 6, 2).unwrap())
);
assert_eq!(NaiveDate::MIN.pred_opt(), None);

const fn checked_add_signed(self: Self, rhs: TimeDelta) -> Option<NaiveDate>

Adds the number of whole days in the given TimeDelta to the current date.

Errors

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

Example

use chrono::{NaiveDate, TimeDelta};

let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
assert_eq!(
    d.checked_add_signed(TimeDelta::try_days(40).unwrap()),
    Some(NaiveDate::from_ymd_opt(2015, 10, 15).unwrap())
);
assert_eq!(
    d.checked_add_signed(TimeDelta::try_days(-40).unwrap()),
    Some(NaiveDate::from_ymd_opt(2015, 7, 27).unwrap())
);
assert_eq!(d.checked_add_signed(TimeDelta::try_days(1_000_000_000).unwrap()), None);
assert_eq!(d.checked_add_signed(TimeDelta::try_days(-1_000_000_000).unwrap()), None);
assert_eq!(NaiveDate::MAX.checked_add_signed(TimeDelta::try_days(1).unwrap()), None);

const fn checked_sub_signed(self: Self, rhs: TimeDelta) -> Option<NaiveDate>

Subtracts the number of whole days in the given TimeDelta from the current date.

Errors

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

Example

use chrono::{NaiveDate, TimeDelta};

let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
assert_eq!(
    d.checked_sub_signed(TimeDelta::try_days(40).unwrap()),
    Some(NaiveDate::from_ymd_opt(2015, 7, 27).unwrap())
);
assert_eq!(
    d.checked_sub_signed(TimeDelta::try_days(-40).unwrap()),
    Some(NaiveDate::from_ymd_opt(2015, 10, 15).unwrap())
);
assert_eq!(d.checked_sub_signed(TimeDelta::try_days(1_000_000_000).unwrap()), None);
assert_eq!(d.checked_sub_signed(TimeDelta::try_days(-1_000_000_000).unwrap()), None);
assert_eq!(NaiveDate::MIN.checked_sub_signed(TimeDelta::try_days(1).unwrap()), None);

const fn signed_duration_since(self: Self, rhs: NaiveDate) -> TimeDelta

Subtracts another NaiveDate from the current date. Returns a TimeDelta of integral numbers.

This does not overflow or underflow at all, as all possible output fits in the range of TimeDelta.

Example

use chrono::{NaiveDate, TimeDelta};

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

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

const fn years_since(self: &Self, base: Self) -> Option<u32>

Returns the number of whole years from the given base until self.

Errors

Returns None if base > self.

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

Formats the date 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::format::strftime::StrftimeItems;
use chrono::NaiveDate;

let fmt = StrftimeItems::new("%Y-%m-%d");
let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
assert_eq!(d.format_with_items(fmt.clone()).to_string(), "2015-09-05");
assert_eq!(d.format("%Y-%m-%d").to_string(), "2015-09-05");

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

# use chrono::NaiveDate;
# use chrono::format::strftime::StrftimeItems;
# let fmt = StrftimeItems::new("%Y-%m-%d").clone();
# let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
assert_eq!(format!("{}", d.format_with_items(fmt)), "2015-09-05");

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

Formats the date 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.)

Panics

Converting or formatting the returned DelayedFormat panics if the format string is wrong. Because of this delayed failure, you are recommended to immediately use the DelayedFormat value.

Example

use chrono::NaiveDate;

let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
assert_eq!(d.format("%Y-%m-%d").to_string(), "2015-09-05");
assert_eq!(d.format("%A, %-d %B, %C%y").to_string(), "Saturday, 5 September, 2015");

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

# use chrono::NaiveDate;
# let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
assert_eq!(format!("{}", d.format("%Y-%m-%d")), "2015-09-05");
assert_eq!(format!("{}", d.format("%A, %-d %B, %C%y")), "Saturday, 5 September, 2015");

const fn iter_days(self: &Self) -> NaiveDateDaysIterator

Returns an iterator that steps by days across all representable dates.

Example

# use chrono::NaiveDate;

let expected = [
    NaiveDate::from_ymd_opt(2016, 2, 27).unwrap(),
    NaiveDate::from_ymd_opt(2016, 2, 28).unwrap(),
    NaiveDate::from_ymd_opt(2016, 2, 29).unwrap(),
    NaiveDate::from_ymd_opt(2016, 3, 1).unwrap(),
];

let mut count = 0;
for (idx, d) in NaiveDate::from_ymd_opt(2016, 2, 27).unwrap().iter_days().take(4).enumerate() {
    assert_eq!(d, expected[idx]);
    count += 1;
}
assert_eq!(count, 4);

for d in NaiveDate::from_ymd_opt(2016, 3, 1).unwrap().iter_days().rev().take(4) {
    count -= 1;
    assert_eq!(d, expected[count]);
}

const fn iter_weeks(self: &Self) -> NaiveDateWeeksIterator

Returns an iterator that steps by weeks across all representable dates.

Example

# use chrono::NaiveDate;

let expected = [
    NaiveDate::from_ymd_opt(2016, 2, 27).unwrap(),
    NaiveDate::from_ymd_opt(2016, 3, 5).unwrap(),
    NaiveDate::from_ymd_opt(2016, 3, 12).unwrap(),
    NaiveDate::from_ymd_opt(2016, 3, 19).unwrap(),
];

let mut count = 0;
for (idx, d) in NaiveDate::from_ymd_opt(2016, 2, 27).unwrap().iter_weeks().take(4).enumerate() {
    assert_eq!(d, expected[idx]);
    count += 1;
}
assert_eq!(count, 4);

for d in NaiveDate::from_ymd_opt(2016, 3, 19).unwrap().iter_weeks().rev().take(4) {
    count -= 1;
    assert_eq!(d, expected[count]);
}

const fn week(self: &Self, start: Weekday) -> NaiveWeek

Returns the NaiveWeek that the date belongs to, starting with the Weekday specified.

const fn leap_year(self: &Self) -> bool

Returns true if this is a leap year.

# use chrono::NaiveDate;
assert_eq!(NaiveDate::from_ymd_opt(2000, 1, 1).unwrap().leap_year(), true);
assert_eq!(NaiveDate::from_ymd_opt(2001, 1, 1).unwrap().leap_year(), false);
assert_eq!(NaiveDate::from_ymd_opt(2002, 1, 1).unwrap().leap_year(), false);
assert_eq!(NaiveDate::from_ymd_opt(2003, 1, 1).unwrap().leap_year(), false);
assert_eq!(NaiveDate::from_ymd_opt(2004, 1, 1).unwrap().leap_year(), true);
assert_eq!(NaiveDate::from_ymd_opt(2100, 1, 1).unwrap().leap_year(), false);

impl Add for NaiveDate

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

impl Add for NaiveDate

fn add(self: Self, months: Months) -> <Self as >::Output

impl Add for NaiveDate

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

impl AddAssign for NaiveDate

fn add_assign(self: &mut Self, rhs: TimeDelta)

impl Clone for NaiveDate

fn clone(self: &Self) -> NaiveDate

impl Copy for NaiveDate

impl Datelike for NaiveDate

fn year(self: &Self) -> i32

Returns the year number in the calendar date.

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().year(), 2015);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().year(), -308); // 309 BCE

fn month(self: &Self) -> u32

Returns the month number starting from 1.

The return value ranges from 1 to 12.

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().month(), 9);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().month(), 3);

fn month0(self: &Self) -> u32

Returns the month number starting from 0.

The return value ranges from 0 to 11.

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().month0(), 8);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().month0(), 2);

fn day(self: &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.)

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().day(), 8);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().day(), 14);

Combined with NaiveDate::pred_opt, one can determine the number of days in a particular month. (Note that this panics when year is out of range.)

use chrono::{Datelike, NaiveDate};

fn ndays_in_month(year: i32, month: u32) -> u32 {
    // the first day of the next month...
    let (y, m) = if month == 12 { (year + 1, 1) } else { (year, month + 1) };
    let d = NaiveDate::from_ymd_opt(y, m, 1).unwrap();

    // ...is preceded by the last day of the original month
    d.pred_opt().unwrap().day()
}

assert_eq!(ndays_in_month(2015, 8), 31);
assert_eq!(ndays_in_month(2015, 9), 30);
assert_eq!(ndays_in_month(2015, 12), 31);
assert_eq!(ndays_in_month(2016, 2), 29);
assert_eq!(ndays_in_month(2017, 2), 28);

fn day0(self: &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.)

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().day0(), 7);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().day0(), 13);

fn ordinal(self: &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.)

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().ordinal(), 251);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().ordinal(), 74);

Combined with NaiveDate::pred_opt, one can determine the number of days in a particular year. (Note that this panics when year is out of range.)

use chrono::{Datelike, NaiveDate};

fn ndays_in_year(year: i32) -> u32 {
    // the first day of the next year...
    let d = NaiveDate::from_ymd_opt(year + 1, 1, 1).unwrap();

    // ...is preceded by the last day of the original year
    d.pred_opt().unwrap().ordinal()
}

assert_eq!(ndays_in_year(2015), 365);
assert_eq!(ndays_in_year(2016), 366);
assert_eq!(ndays_in_year(2017), 365);
assert_eq!(ndays_in_year(2000), 366);
assert_eq!(ndays_in_year(2100), 365);

fn ordinal0(self: &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.)

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().ordinal0(), 250);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().ordinal0(), 73);

fn weekday(self: &Self) -> Weekday

Returns the day of week.

Example

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

assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().weekday(), Weekday::Tue);
assert_eq!(NaiveDate::from_ymd_opt(-308, 3, 14).unwrap().weekday(), Weekday::Fri);

fn iso_week(self: &Self) -> IsoWeek
fn with_year(self: &Self, year: i32) -> Option<NaiveDate>

Makes a new NaiveDate with the year number changed, while keeping the same month and day.

This method assumes you want to work on the date as a year-month-day value. Don't use it if you want the ordinal to stay the same after changing the year, of if you want the week and weekday values to stay the same.

Errors

Returns None if:

  • The resulting date does not exist (February 29 in a non-leap year).
  • The year is out of range for a NaiveDate.

Examples

use chrono::{Datelike, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_year(2016),
    Some(NaiveDate::from_ymd_opt(2016, 9, 8).unwrap())
);
assert_eq!(
    NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_year(-308),
    Some(NaiveDate::from_ymd_opt(-308, 9, 8).unwrap())
);

A leap day (February 29) is a case where this method can return None.

# use chrono::{NaiveDate, Datelike};
assert!(NaiveDate::from_ymd_opt(2016, 2, 29).unwrap().with_year(2015).is_none());
assert!(NaiveDate::from_ymd_opt(2016, 2, 29).unwrap().with_year(2020).is_some());

Don't use with_year if you want the ordinal date to stay the same:

# use chrono::{Datelike, NaiveDate};
assert_ne!(
    NaiveDate::from_yo_opt(2020, 100).unwrap().with_year(2023).unwrap(),
    NaiveDate::from_yo_opt(2023, 100).unwrap() // result is 2023-101
);

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

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

Errors

Returns None if:

  • The resulting date does not exist (for example month(4) when day of the month is 31).
  • The value for month is invalid.

Examples

use chrono::{Datelike, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_month(10),
    Some(NaiveDate::from_ymd_opt(2015, 10, 8).unwrap())
);
assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_month(13), None); // No month 13
assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 30).unwrap().with_month(2), None); // No Feb 30

Don't combine multiple Datelike::with_* methods. The intermediate value may not exist.

use chrono::{Datelike, NaiveDate};

fn with_year_month(date: NaiveDate, year: i32, month: u32) -> Option<NaiveDate> {
    date.with_year(year)?.with_month(month)
}
let d = NaiveDate::from_ymd_opt(2020, 2, 29).unwrap();
assert!(with_year_month(d, 2019, 1).is_none()); // fails because of invalid intermediate value

// Correct version:
fn with_year_month_fixed(date: NaiveDate, year: i32, month: u32) -> Option<NaiveDate> {
    NaiveDate::from_ymd_opt(year, month, date.day())
}
let d = NaiveDate::from_ymd_opt(2020, 2, 29).unwrap();
assert_eq!(with_year_month_fixed(d, 2019, 1), NaiveDate::from_ymd_opt(2019, 1, 29));

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

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

Errors

Returns None if:

  • The resulting date does not exist (for example month0(3) when day of the month is 31).
  • The value for month0 is invalid.

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_month0(9),
    Some(NaiveDate::from_ymd_opt(2015, 10, 8).unwrap())
);
assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_month0(12), None); // No month 12
assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 30).unwrap().with_month0(1), None); // No Feb 30

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

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

Errors

Returns None if:

  • The resulting date does not exist (for example day(31) in April).
  • The value for day is invalid.

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_day(30),
    Some(NaiveDate::from_ymd_opt(2015, 9, 30).unwrap())
);
assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_day(31), None);
// no September 31

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

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

Errors

Returns None if:

  • The resulting date does not exist (for example day(30) in April).
  • The value for day0 is invalid.

Example

use chrono::{Datelike, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_day0(29),
    Some(NaiveDate::from_ymd_opt(2015, 9, 30).unwrap())
);
assert_eq!(NaiveDate::from_ymd_opt(2015, 9, 8).unwrap().with_day0(30), None);
// no September 31

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

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

Errors

Returns None if:

  • The resulting date does not exist (with_ordinal(366) in a non-leap year).
  • The value for ordinal is invalid.

Example

use chrono::{NaiveDate, Datelike};

assert_eq!(NaiveDate::from_ymd_opt(2015, 1, 1).unwrap().with_ordinal(60),
           Some(NaiveDate::from_ymd_opt(2015, 3, 1).unwrap()));
assert_eq!(NaiveDate::from_ymd_opt(2015, 1, 1).unwrap().with_ordinal(366),
           None); // 2015 had only 365 days

assert_eq!(NaiveDate::from_ymd_opt(2016, 1, 1).unwrap().with_ordinal(60),
           Some(NaiveDate::from_ymd_opt(2016, 2, 29).unwrap()));
assert_eq!(NaiveDate::from_ymd_opt(2016, 1, 1).unwrap().with_ordinal(366),
           Some(NaiveDate::from_ymd_opt(2016, 12, 31).unwrap()));

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

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

Errors

Returns None if:

  • The resulting date does not exist (with_ordinal0(365) in a non-leap year).
  • The value for ordinal0 is invalid.

Example

use chrono::{NaiveDate, Datelike};

assert_eq!(NaiveDate::from_ymd_opt(2015, 1, 1).unwrap().with_ordinal0(59),
           Some(NaiveDate::from_ymd_opt(2015, 3, 1).unwrap()));
assert_eq!(NaiveDate::from_ymd_opt(2015, 1, 1).unwrap().with_ordinal0(365),
           None); // 2015 had only 365 days

assert_eq!(NaiveDate::from_ymd_opt(2016, 1, 1).unwrap().with_ordinal0(59),
           Some(NaiveDate::from_ymd_opt(2016, 2, 29).unwrap()));
assert_eq!(NaiveDate::from_ymd_opt(2016, 1, 1).unwrap().with_ordinal0(365),
           Some(NaiveDate::from_ymd_opt(2016, 12, 31).unwrap()));

impl Debug for NaiveDate

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

impl Default for NaiveDate

fn default() -> Self

impl Display for NaiveDate

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

impl Eq for NaiveDate

impl Freeze for NaiveDate

impl From for NaiveDate

fn from(naive_datetime: NaiveDateTime) -> Self

impl FromStr for NaiveDate

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

impl Hash for NaiveDate

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

impl Ord for NaiveDate

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

impl PartialEq for NaiveDate

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

impl PartialOrd for NaiveDate

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

impl RefUnwindSafe for NaiveDate

impl Send for NaiveDate

impl StructuralPartialEq for NaiveDate

impl Sub for NaiveDate

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

impl Sub for NaiveDate

fn sub(self: Self, months: Months) -> <Self as >::Output

impl Sub for NaiveDate

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

impl Sub for NaiveDate

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

impl SubAssign for NaiveDate

fn sub_assign(self: &mut Self, rhs: TimeDelta)

impl Sync for NaiveDate

impl Unpin for NaiveDate

impl UnsafeUnpin for NaiveDate

impl UnwindSafe for NaiveDate

impl<T> Any for NaiveDate

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for NaiveDate

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for NaiveDate

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for NaiveDate

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for NaiveDate

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for NaiveDate

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T> ToString for NaiveDate

fn to_string(self: &Self) -> String

impl<T, U> Into for NaiveDate

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for NaiveDate

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for NaiveDate

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>