Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Datelike

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:

  • with_year changes the year component of a year-month-day value. Don’t use this method 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.
  • Don’t combine two with_* methods to change two components of the date. For example to change both the year and month components of a date. This could fail because an intermediate value does not exist, while the final date would be valid.

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.

Fully qualified path: chrono::traits::Datelike

pub trait Datelike<T>

Trait functions

year

Returns the year number in the calendar date.

Fully qualified path: chrono::traits::Datelike::year

fn year(self: @T) -> u32

year_ce

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

Fully qualified path: chrono::traits::Datelike::year_ce

fn year_ce(self: @T) -> (bool, u32)

quarter

Returns the quarter number starting from 1.

The return value ranges from 1 to 4.

Fully qualified path: chrono::traits::Datelike::quarter

fn quarter(self: @T) -> u32

month

Returns the month number starting from 1.

The return value ranges from 1 to 12.

Fully qualified path: chrono::traits::Datelike::month

fn month(self: @T) -> u32

month0

Returns the month number starting from 0.

The return value ranges from 0 to 11.

Fully qualified path: chrono::traits::Datelike::month0

fn month0(self: @T) -> u32

day

Returns the day of month starting from 1.

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

Fully qualified path: chrono::traits::Datelike::day

fn day(self: @T) -> u32

day0

Returns the day of month starting from 0.

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

Fully qualified path: chrono::traits::Datelike::day0

fn day0(self: @T) -> u32

ordinal

Returns the day of year starting from 1.

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

Fully qualified path: chrono::traits::Datelike::ordinal

fn ordinal(self: @T) -> u32

ordinal0

Returns the day of year starting from 0.

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

Fully qualified path: chrono::traits::Datelike::ordinal0

fn ordinal0(self: @T) -> u32

weekday

Returns the day of week.

Fully qualified path: chrono::traits::Datelike::weekday

fn weekday(self: @T) -> Weekday

iso_week

Returns the ISO week.

Fully qualified path: chrono::traits::Datelike::iso_week

fn iso_week(self: @T) -> IsoWeek

with_year

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

Fully qualified path: chrono::traits::Datelike::with_year

fn with_year(self: @T, year: u32) -> Option<T>

with_month

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

Fully qualified path: chrono::traits::Datelike::with_month

fn with_month(self: @T, month: u32) -> Option<T>

with_month0

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.

Fully qualified path: chrono::traits::Datelike::with_month0

fn with_month0(self: @T, month0: u32) -> Option<T>

with_day

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.

Fully qualified path: chrono::traits::Datelike::with_day

fn with_day(self: @T, day: u32) -> Option<T>

with_day0

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.

Fully qualified path: chrono::traits::Datelike::with_day0

fn with_day0(self: @T, day0: u32) -> Option<T>

with_ordinal

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.

Fully qualified path: chrono::traits::Datelike::with_ordinal

fn with_ordinal(self: @T, ordinal: u32) -> Option<T>

with_ordinal0

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.

Fully qualified path: chrono::traits::Datelike::with_ordinal0

fn with_ordinal0(self: @T, ordinal0: u32) -> Option<T>

num_days_from_ce

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

Fully qualified path: chrono::traits::Datelike::num_days_from_ce

fn num_days_from_ce(self: @T) -> i32

num_days_in_month

Get the length in days of the month

Fully qualified path: chrono::traits::Datelike::num_days_in_month

fn num_days_in_month(self: @T) -> u8