Trait Datelike

trait Datelike: Sized

The common set of methods for date component.

Methods such as year, month, day and weekday can be used to get basic information about the date.

The with_* methods can change the date.

Warning

The with_* methods can be convenient to change a single component of a date, but they must be used with some care. Examples to watch out for:

For more complex changes to a date, it is best to use the methods on NaiveDate to create a new value instead of altering an existing date.

Required Methods

fn year(self: &Self) -> i32

Returns the year number in the calendar date.

fn month(self: &Self) -> u32

Returns the month number starting from 1.

The return value ranges from 1 to 12.

fn month0(self: &Self) -> u32

Returns the month number starting from 0.

The return value ranges from 0 to 11.

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

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

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

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

fn weekday(self: &Self) -> Weekday

Returns the day of week.

fn iso_week(self: &Self) -> IsoWeek

Returns the ISO week.

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

Makes a new value 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 when:

  • The resulting date does not exist (February 29 in a non-leap year).
  • The year is out of range for NaiveDate.
  • In case of DateTime<Tz> if the resulting date and time fall within a timezone transition such as from DST to standard time.

Examples

use chrono::{Datelike, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2020, 5, 13).unwrap().with_year(2023).unwrap(),
    NaiveDate::from_ymd_opt(2023, 5, 13).unwrap()
);
// Resulting date 2023-02-29 does not exist:
assert!(NaiveDate::from_ymd_opt(2020, 2, 29).unwrap().with_year(2023).is_none());

// Don't use `with_year` if you want the ordinal date to stay the same:
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<Self>

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

Errors

Returns None when:

  • The resulting date does not exist (for example month(4) when day of the month is 31).
  • In case of DateTime<Tz> if the resulting date and time fall within a timezone transition such as from DST to standard time.
  • The value for month is out of range.

Examples

use chrono::{Datelike, NaiveDate};

assert_eq!(
    NaiveDate::from_ymd_opt(2023, 5, 12).unwrap().with_month(9).unwrap(),
    NaiveDate::from_ymd_opt(2023, 9, 12).unwrap()
);
// Resulting date 2023-09-31 does not exist:
assert!(NaiveDate::from_ymd_opt(2023, 5, 31).unwrap().with_month(9).is_none());

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<Self>

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

Errors

Returns None when:

  • The resulting date does not exist (for example month0(3) when day of the month is 31).
  • In case of DateTime<Tz> if the resulting date and time fall within a timezone transition such as from DST to standard time.
  • The value for month0 is out of range.
fn with_day(self: &Self, day: u32) -> Option<Self>

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

Errors

Returns None when:

  • The resulting date does not exist (for example day(31) in April).
  • In case of DateTime<Tz> if the resulting date and time fall within a timezone transition such as from DST to standard time.
  • The value for day is out of range.
fn with_day0(self: &Self, day0: u32) -> Option<Self>

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

Errors

Returns None when:

  • The resulting date does not exist (for example day0(30) in April).
  • In case of DateTime<Tz> if the resulting date and time fall within a timezone transition such as from DST to standard time.
  • The value for day0 is out of range.
fn with_ordinal(self: &Self, ordinal: u32) -> Option<Self>

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

Errors

Returns None when:

  • The resulting date does not exist (with_ordinal(366) in a non-leap year).
  • In case of DateTime<Tz> if the resulting date and time fall within a timezone transition such as from DST to standard time.
  • The value for ordinal is out of range.
fn with_ordinal0(self: &Self, ordinal0: u32) -> Option<Self>

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

Errors

Returns None when:

  • The resulting date does not exist (with_ordinal0(365) in a non-leap year).
  • In case of DateTime<Tz> if the resulting date and time fall within a timezone transition such as from DST to standard time.
  • The value for ordinal0 is out of range.

Provided Methods

fn year_ce(self: &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: &Self) -> i32

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

Examples

use chrono::{Datelike, NaiveDate};

assert_eq!(NaiveDate::from_ymd_opt(1970, 1, 1).unwrap().num_days_from_ce(), 719_163);
assert_eq!(NaiveDate::from_ymd_opt(2, 1, 1).unwrap().num_days_from_ce(), 366);
assert_eq!(NaiveDate::from_ymd_opt(1, 1, 1).unwrap().num_days_from_ce(), 1);
assert_eq!(NaiveDate::from_ymd_opt(0, 1, 1).unwrap().num_days_from_ce(), -365);

Implementors