Trait chrono::traits::Datelike

source · 
pub trait Datelike: Sized {

Show 18 methods    // Required methods
    fn year(&self) -> i32;
    fn month(&self) -> u32;
    fn month0(&self) -> u32;
    fn day(&self) -> u32;
    fn day0(&self) -> u32;
    fn ordinal(&self) -> u32;
    fn ordinal0(&self) -> u32;
    fn weekday(&self) -> Weekday;
    fn iso_week(&self) -> IsoWeek;
    fn with_year(&self, year: i32) -> Option<Self>;
    fn with_month(&self, month: u32) -> Option<Self>;
    fn with_month0(&self, month0: u32) -> Option<Self>;
    fn with_day(&self, day: u32) -> Option<Self>;
    fn with_day0(&self, day0: u32) -> Option<Self>;
    fn with_ordinal(&self, ordinal: u32) -> Option<Self>;
    fn with_ordinal0(&self, ordinal0: u32) -> Option<Self>;

    // Provided methods
    fn year_ce(&self) -> (bool, u32) { ... }
    fn num_days_from_ce(&self) -> i32 { ... }

}
Expand description

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.

Required Methods§

source

fn year(&self) -> i32

Returns the year number in the calendar date.

source

fn month(&self) -> u32

Returns the month number starting from 1.

The return value ranges from 1 to 12.

source

fn month0(&self) -> u32

Returns the month number starting from 0.

The return value ranges from 0 to 11.

source

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

source

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

source

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

source

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

source

fn weekday(&self) -> Weekday

Returns the day of week.

source

fn iso_week(&self) -> IsoWeek

Returns the ISO week.

source

fn with_year(&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
);
source

fn with_month(&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));
source

fn with_month0(&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.
source

fn with_day(&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.
source

fn with_day0(&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.
source

fn with_ordinal(&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.
source

fn with_ordinal0(&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§

source

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

source

fn num_days_from_ce(&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);

Object Safety§

This trait is not object safe.

Implementors§