Struct time::Date

pub struct Date { /* private fields */ }

Date in the proleptic Gregorian calendar.

By default, years between ±9999 inclusive are representable. This can be expanded to ±999,999 inclusive by enabling the large-dates crate feature. Doing so has performance implications and introduces some ambiguities when parsing.

Implementations

impl Date

pub const MIN: Self = _

The minimum valid Date.

The value of this may vary depending on the feature flags enabled.

pub const MAX: Self = _

The maximum valid Date.

The value of this may vary depending on the feature flags enabled.

pub const fn from_calendar_date( year: i32, month: Month, day: u8 ) -> Result<Self, ComponentRange>

Attempt to create a Date from the year, month, and day.

assert!(Date::from_calendar_date(2019, Month::January, 1).is_ok());
assert!(Date::from_calendar_date(2019, Month::December, 31).is_ok());

assert!(Date::from_calendar_date(2019, Month::February, 29).is_err()); // 2019 isn't a leap year.

pub const fn from_ordinal_date( year: i32, ordinal: u16 ) -> Result<Self, ComponentRange>

Attempt to create a Date from the year and ordinal day number.

assert!(Date::from_ordinal_date(2019, 1).is_ok());
assert!(Date::from_ordinal_date(2019, 365).is_ok());

assert!(Date::from_ordinal_date(2019, 366).is_err()); // 2019 isn't a leap year.

pub const fn from_iso_week_date( year: i32, week: u8, weekday: Weekday ) -> Result<Self, ComponentRange>

Attempt to create a Date from the ISO year, week, and weekday.

assert!(Date::from_iso_week_date(2019, 1, Monday).is_ok());
assert!(Date::from_iso_week_date(2019, 1, Tuesday).is_ok());
assert!(Date::from_iso_week_date(2020, 53, Friday).is_ok());

assert!(Date::from_iso_week_date(2019, 53, Monday).is_err()); // 2019 doesn't have 53 weeks.

pub const fn from_julian_day(julian_day: i32) -> Result<Self, ComponentRange>

Create a Date from the Julian day.

The algorithm to perform this conversion is derived from one provided by Peter Baum; it is freely available here.

assert_eq!(Date::from_julian_day(0), Ok(date!(-4713 - 11 - 24)));
assert_eq!(Date::from_julian_day(2_451_545), Ok(date!(2000 - 01 - 01)));
assert_eq!(Date::from_julian_day(2_458_485), Ok(date!(2019 - 01 - 01)));
assert_eq!(Date::from_julian_day(2_458_849), Ok(date!(2019 - 12 - 31)));

pub const fn year(self) -> i32

Get the year of the date.

assert_eq!(date!(2019 - 01 - 01).year(), 2019);
assert_eq!(date!(2019 - 12 - 31).year(), 2019);
assert_eq!(date!(2020 - 01 - 01).year(), 2020);

pub const fn month(self) -> Month

Get the month.

assert_eq!(date!(2019 - 01 - 01).month(), Month::January);
assert_eq!(date!(2019 - 12 - 31).month(), Month::December);

pub const fn day(self) -> u8

Get the day of the month.

The returned value will always be in the range 1..=31.

assert_eq!(date!(2019 - 01 - 01).day(), 1);
assert_eq!(date!(2019 - 12 - 31).day(), 31);

pub const fn ordinal(self) -> u16

Get the day of the year.

The returned value will always be in the range 1..=366 (1..=365 for common years).

assert_eq!(date!(2019 - 01 - 01).ordinal(), 1);
assert_eq!(date!(2019 - 12 - 31).ordinal(), 365);

pub const fn iso_week(self) -> u8

Get the ISO week number.

The returned value will always be in the range 1..=53.

assert_eq!(date!(2019 - 01 - 01).iso_week(), 1);
assert_eq!(date!(2019 - 10 - 04).iso_week(), 40);
assert_eq!(date!(2020 - 01 - 01).iso_week(), 1);
assert_eq!(date!(2020 - 12 - 31).iso_week(), 53);
assert_eq!(date!(2021 - 01 - 01).iso_week(), 53);

pub const fn sunday_based_week(self) -> u8

Get the week number where week 1 begins on the first Sunday.

The returned value will always be in the range 0..=53.

assert_eq!(date!(2019 - 01 - 01).sunday_based_week(), 0);
assert_eq!(date!(2020 - 01 - 01).sunday_based_week(), 0);
assert_eq!(date!(2020 - 12 - 31).sunday_based_week(), 52);
assert_eq!(date!(2021 - 01 - 01).sunday_based_week(), 0);

pub const fn monday_based_week(self) -> u8

Get the week number where week 1 begins on the first Monday.

The returned value will always be in the range 0..=53.

assert_eq!(date!(2019 - 01 - 01).monday_based_week(), 0);
assert_eq!(date!(2020 - 01 - 01).monday_based_week(), 0);
assert_eq!(date!(2020 - 12 - 31).monday_based_week(), 52);
assert_eq!(date!(2021 - 01 - 01).monday_based_week(), 0);

pub const fn to_calendar_date(self) -> (i32, Month, u8)

Get the year, month, and day.

assert_eq!(
    date!(2019 - 01 - 01).to_calendar_date(),
    (2019, Month::January, 1)
);

pub const fn to_ordinal_date(self) -> (i32, u16)

Get the year and ordinal day number.

assert_eq!(date!(2019 - 01 - 01).to_ordinal_date(), (2019, 1));

pub const fn to_iso_week_date(self) -> (i32, u8, Weekday)

Get the ISO 8601 year, week number, and weekday.

assert_eq!(date!(2019 - 01 - 01).to_iso_week_date(), (2019, 1, Tuesday));
assert_eq!(date!(2019 - 10 - 04).to_iso_week_date(), (2019, 40, Friday));
assert_eq!(
    date!(2020 - 01 - 01).to_iso_week_date(),
    (2020, 1, Wednesday)
);
assert_eq!(
    date!(2020 - 12 - 31).to_iso_week_date(),
    (2020, 53, Thursday)
);
assert_eq!(date!(2021 - 01 - 01).to_iso_week_date(), (2020, 53, Friday));

pub const fn weekday(self) -> Weekday

Get the weekday.

assert_eq!(date!(2019 - 01 - 01).weekday(), Tuesday);
assert_eq!(date!(2019 - 02 - 01).weekday(), Friday);
assert_eq!(date!(2019 - 03 - 01).weekday(), Friday);
assert_eq!(date!(2019 - 04 - 01).weekday(), Monday);
assert_eq!(date!(2019 - 05 - 01).weekday(), Wednesday);
assert_eq!(date!(2019 - 06 - 01).weekday(), Saturday);
assert_eq!(date!(2019 - 07 - 01).weekday(), Monday);
assert_eq!(date!(2019 - 08 - 01).weekday(), Thursday);
assert_eq!(date!(2019 - 09 - 01).weekday(), Sunday);
assert_eq!(date!(2019 - 10 - 01).weekday(), Tuesday);
assert_eq!(date!(2019 - 11 - 01).weekday(), Friday);
assert_eq!(date!(2019 - 12 - 01).weekday(), Sunday);

pub const fn next_day(self) -> Option<Self>

Get the next calendar date.

assert_eq!(
    date!(2019 - 01 - 01).next_day(),
    Some(date!(2019 - 01 - 02))
);
assert_eq!(
    date!(2019 - 01 - 31).next_day(),
    Some(date!(2019 - 02 - 01))
);
assert_eq!(
    date!(2019 - 12 - 31).next_day(),
    Some(date!(2020 - 01 - 01))
);
assert_eq!(Date::MAX.next_day(), None);

pub const fn previous_day(self) -> Option<Self>

Get the previous calendar date.

assert_eq!(
    date!(2019 - 01 - 02).previous_day(),
    Some(date!(2019 - 01 - 01))
);
assert_eq!(
    date!(2019 - 02 - 01).previous_day(),
    Some(date!(2019 - 01 - 31))
);
assert_eq!(
    date!(2020 - 01 - 01).previous_day(),
    Some(date!(2019 - 12 - 31))
);
assert_eq!(Date::MIN.previous_day(), None);

pub const fn next_occurrence(self, weekday: Weekday) -> Self

Calculates the first occurrence of a weekday that is strictly later than a given Date.

Panics

Panics if an overflow occurred.

Examples

assert_eq!(
    date!(2023 - 06 - 28).next_occurrence(Weekday::Monday),
    date!(2023 - 07 - 03)
);
assert_eq!(
    date!(2023 - 06 - 19).next_occurrence(Weekday::Monday),
    date!(2023 - 06 - 26)
);

pub const fn prev_occurrence(self, weekday: Weekday) -> Self

Calculates the first occurrence of a weekday that is strictly earlier than a given Date.

Panics

Panics if an overflow occurred.

Examples

assert_eq!(
    date!(2023 - 06 - 28).prev_occurrence(Weekday::Monday),
    date!(2023 - 06 - 26)
);
assert_eq!(
    date!(2023 - 06 - 19).prev_occurrence(Weekday::Monday),
    date!(2023 - 06 - 12)
);

pub const fn nth_next_occurrence(self, weekday: Weekday, n: u8) -> Self

Calculates the nth occurrence of a weekday that is strictly later than a given Date.

Panics

Panics if an overflow occurred or if n == 0.

Examples

assert_eq!(
    date!(2023 - 06 - 25).nth_next_occurrence(Weekday::Monday, 5),
    date!(2023 - 07 - 24)
);
assert_eq!(
    date!(2023 - 06 - 26).nth_next_occurrence(Weekday::Monday, 5),
    date!(2023 - 07 - 31)
);

pub const fn nth_prev_occurrence(self, weekday: Weekday, n: u8) -> Self

Calculates the nth occurrence of a weekday that is strictly earlier than a given Date.

Panics

Panics if an overflow occurred or if n == 0.

Examples

assert_eq!(
    date!(2023 - 06 - 27).nth_prev_occurrence(Weekday::Monday, 3),
    date!(2023 - 06 - 12)
);
assert_eq!(
    date!(2023 - 06 - 26).nth_prev_occurrence(Weekday::Monday, 3),
    date!(2023 - 06 - 05)
);

pub const fn to_julian_day(self) -> i32

Get the Julian day for the date.

The algorithm to perform this conversion is derived from one provided by Peter Baum; it is freely available here.

assert_eq!(date!(-4713 - 11 - 24).to_julian_day(), 0);
assert_eq!(date!(2000 - 01 - 01).to_julian_day(), 2_451_545);
assert_eq!(date!(2019 - 01 - 01).to_julian_day(), 2_458_485);
assert_eq!(date!(2019 - 12 - 31).to_julian_day(), 2_458_849);

pub const fn checked_add(self, duration: Duration) -> Option<Self>

Computes self + duration, returning None if an overflow occurred.

assert_eq!(Date::MAX.checked_add(1.days()), None);
assert_eq!(Date::MIN.checked_add((-2).days()), None);
assert_eq!(
    date!(2020 - 12 - 31).checked_add(2.days()),
    Some(date!(2021 - 01 - 02))
);

Note

This function only takes whole days into account.

assert_eq!(Date::MAX.checked_add(23.hours()), Some(Date::MAX));
assert_eq!(Date::MIN.checked_add((-23).hours()), Some(Date::MIN));
assert_eq!(
    date!(2020 - 12 - 31).checked_add(23.hours()),
    Some(date!(2020 - 12 - 31))
);
assert_eq!(
    date!(2020 - 12 - 31).checked_add(47.hours()),
    Some(date!(2021 - 01 - 01))
);

pub const fn checked_sub(self, duration: Duration) -> Option<Self>

Computes self - duration, returning None if an overflow occurred.

assert_eq!(Date::MAX.checked_sub((-2).days()), None);
assert_eq!(Date::MIN.checked_sub(1.days()), None);
assert_eq!(
    date!(2020 - 12 - 31).checked_sub(2.days()),
    Some(date!(2020 - 12 - 29))
);

Note

This function only takes whole days into account.

assert_eq!(Date::MAX.checked_sub((-23).hours()), Some(Date::MAX));
assert_eq!(Date::MIN.checked_sub(23.hours()), Some(Date::MIN));
assert_eq!(
    date!(2020 - 12 - 31).checked_sub(23.hours()),
    Some(date!(2020 - 12 - 31))
);
assert_eq!(
    date!(2020 - 12 - 31).checked_sub(47.hours()),
    Some(date!(2020 - 12 - 30))
);

pub const fn saturating_add(self, duration: Duration) -> Self

Computes self + duration, saturating value on overflow.

assert_eq!(Date::MAX.saturating_add(1.days()), Date::MAX);
assert_eq!(Date::MIN.saturating_add((-2).days()), Date::MIN);
assert_eq!(
    date!(2020 - 12 - 31).saturating_add(2.days()),
    date!(2021 - 01 - 02)
);

Note

This function only takes whole days into account.

assert_eq!(
    date!(2020 - 12 - 31).saturating_add(23.hours()),
    date!(2020 - 12 - 31)
);
assert_eq!(
    date!(2020 - 12 - 31).saturating_add(47.hours()),
    date!(2021 - 01 - 01)
);

pub const fn saturating_sub(self, duration: Duration) -> Self

Computes self - duration, saturating value on overflow.

assert_eq!(Date::MAX.saturating_sub((-2).days()), Date::MAX);
assert_eq!(Date::MIN.saturating_sub(1.days()), Date::MIN);
assert_eq!(
    date!(2020 - 12 - 31).saturating_sub(2.days()),
    date!(2020 - 12 - 29)
);

Note

This function only takes whole days into account.

assert_eq!(
    date!(2020 - 12 - 31).saturating_sub(23.hours()),
    date!(2020 - 12 - 31)
);
assert_eq!(
    date!(2020 - 12 - 31).saturating_sub(47.hours()),
    date!(2020 - 12 - 30)
);

pub const fn replace_year(self, year: i32) -> Result<Self, ComponentRange>

Replace the year. The month and day will be unchanged.

assert_eq!(
    date!(2022 - 02 - 18).replace_year(2019),
    Ok(date!(2019 - 02 - 18))
);
assert!(date!(2022 - 02 - 18).replace_year(-1_000_000_000).is_err()); // -1_000_000_000 isn't a valid year
assert!(date!(2022 - 02 - 18).replace_year(1_000_000_000).is_err()); // 1_000_000_000 isn't a valid year

pub const fn replace_month(self, month: Month) -> Result<Self, ComponentRange>

Replace the month of the year.

assert_eq!(
    date!(2022 - 02 - 18).replace_month(Month::January),
    Ok(date!(2022 - 01 - 18))
);
assert!(
    date!(2022 - 01 - 30)
        .replace_month(Month::February)
        .is_err()
); // 30 isn't a valid day in February

pub const fn replace_day(self, day: u8) -> Result<Self, ComponentRange>

Replace the day of the month.

assert_eq!(
    date!(2022 - 02 - 18).replace_day(1),
    Ok(date!(2022 - 02 - 01))
);
assert!(date!(2022 - 02 - 18).replace_day(0).is_err()); // 0 isn't a valid day
assert!(date!(2022 - 02 - 18).replace_day(30).is_err()); // 30 isn't a valid day in February

impl Date

Methods to add a Time component, resulting in a PrimitiveDateTime.

pub const fn midnight(self) -> PrimitiveDateTime

Create a PrimitiveDateTime using the existing date. The Time component will be set to midnight.

assert_eq!(date!(1970-01-01).midnight(), datetime!(1970-01-01 0:00));

pub const fn with_time(self, time: Time) -> PrimitiveDateTime

Create a PrimitiveDateTime using the existing date and the provided Time.

assert_eq!(
    date!(1970-01-01).with_time(time!(0:00)),
    datetime!(1970-01-01 0:00),
);

pub const fn with_hms( self, hour: u8, minute: u8, second: u8 ) -> Result<PrimitiveDateTime, ComponentRange>

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970 - 01 - 01).with_hms(0, 0, 0).is_ok());
assert!(date!(1970 - 01 - 01).with_hms(24, 0, 0).is_err());

pub const fn with_hms_milli( self, hour: u8, minute: u8, second: u8, millisecond: u16 ) -> Result<PrimitiveDateTime, ComponentRange>

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970 - 01 - 01).with_hms_milli(0, 0, 0, 0).is_ok());
assert!(date!(1970 - 01 - 01).with_hms_milli(24, 0, 0, 0).is_err());

pub const fn with_hms_micro( self, hour: u8, minute: u8, second: u8, microsecond: u32 ) -> Result<PrimitiveDateTime, ComponentRange>

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970 - 01 - 01).with_hms_micro(0, 0, 0, 0).is_ok());
assert!(date!(1970 - 01 - 01).with_hms_micro(24, 0, 0, 0).is_err());

pub const fn with_hms_nano( self, hour: u8, minute: u8, second: u8, nanosecond: u32 ) -> Result<PrimitiveDateTime, ComponentRange>

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970 - 01 - 01).with_hms_nano(0, 0, 0, 0).is_ok());
assert!(date!(1970 - 01 - 01).with_hms_nano(24, 0, 0, 0).is_err());

impl Date

pub fn format_into( self, output: &mut impl Write, format: &(impl Formattable + ?Sized) ) -> Result<usize, Format>

Format the Date using the provided format description.

pub fn format( self, format: &(impl Formattable + ?Sized) ) -> Result<String, Format>

Format the Date using the provided format description.

let format = format_description::parse("[year]-[month]-[day]")?;
assert_eq!(date!(2020 - 01 - 02).format(&format)?, "2020-01-02");

impl Date

pub fn parse( input: &str, description: &(impl Parsable + ?Sized) ) -> Result<Self, Parse>

Parse a Date from the input using the provided format description.

let format = format_description!("[year]-[month]-[day]");
assert_eq!(Date::parse("2020-01-02", &format)?, date!(2020 - 01 - 02));

Trait Implementations

impl Add<Duration> for Date

type Output = Date

The resulting type after applying the + operator.

fn add(self, duration: Duration) -> Self::Output

Performs the + operation.

impl Add<Duration> for Date

type Output = Date

The resulting type after applying the + operator.

fn add(self, duration: StdDuration) -> Self::Output

Performs the + operation.

impl AddAssign<Duration> for Date

fn add_assign(&mut self, rhs: StdDuration)

Performs the += operation.

impl AddAssign<Duration> for Date

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl Clone for Date

fn clone(&self) -> Date

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Date

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

Formats the value using the given formatter.

impl Display for Date

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

Formats the value using the given formatter.

impl Hash for Date

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 Date

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

Restrict a value to a certain interval.

impl PartialEq for Date

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

fn partial_cmp(&self, other: &Date) -> 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 Sub<Duration> for Date

type Output = Date

The resulting type after applying the - operator.

fn sub(self, duration: StdDuration) -> Self::Output

Performs the - operation.

impl Sub<Duration> for Date

type Output = Date

The resulting type after applying the - operator.

fn sub(self, duration: Duration) -> Self::Output

Performs the - operation.

impl Sub for Date

type Output = Duration

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Self::Output

Performs the - operation.

impl SubAssign<Duration> for Date

fn sub_assign(&mut self, rhs: StdDuration)

Performs the -= operation.

impl SubAssign<Duration> for Date

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl TryFrom<Parsed> for Date

type Error = TryFromParsed

The type returned in the event of a conversion error.

fn try_from(parsed: Parsed) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Date

impl Eq for Date

impl StructuralEq for Date

impl StructuralPartialEq for Date