Struct 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

const fn midnight(self) -> PlainDateTime

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

# use time_macros::{date, datetime};
assert_eq!(date!(1970-01-01).midnight(), datetime!(1970-01-01 0:00));

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

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

# use time_macros::{date, datetime, time};
assert_eq!(
    date!(1970-01-01).with_time(time!(0:00)),
    datetime!(1970-01-01 0:00),
);

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

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

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

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

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

# use time_macros::date;
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());

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

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

# use time_macros::date;
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());

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

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

# use time_macros::date;
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

const MIN: Self = _;

The minimum valid Date.

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

const MAX: Self = _;

The maximum valid Date.

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

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.

# use time::{Date, Month};
assert!(Date::from_calendar_date(2019, Month::January, 1).is_ok());
assert!(Date::from_calendar_date(2019, Month::December, 31).is_ok());

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

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

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

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

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

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.

# use time::{Date, 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());

# use time::{Date, Weekday::*};
assert!(Date::from_iso_week_date(2019, 53, Monday).is_err()); // 2019 doesn't have 53 weeks.

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

Create a Date from the Julian day.

# use time::Date;
# use time_macros::date;
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)));

const fn year(self) -> i32

Get the year of the date.

# use time_macros::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);

const fn month(self) -> Month

Get the month.

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

const fn day(self) -> u8

Get the day of the month.

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

# use time_macros::date;
assert_eq!(date!(2019-01-01).day(), 1);
assert_eq!(date!(2019-12-31).day(), 31);

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

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

const fn iso_week(self) -> u8

Get the ISO week number.

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

# use time_macros::date;
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);

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.

# use time_macros::date;
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);

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.

# use time_macros::date;
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);

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

Get the year, month, and day.

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

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

Get the year and ordinal day number.

# use time_macros::date;
assert_eq!(date!(2019-01-01).to_ordinal_date(), (2019, 1));

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

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

# use time::Weekday::*;
# use time_macros::date;
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));

const fn weekday(self) -> Weekday

Get the weekday.

# use time::Weekday::*;
# use time_macros::date;
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);

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

Get the next calendar date.

# use time::Date;
# use time_macros::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);

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

Get the previous calendar date.

# use time::Date;
# use time_macros::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);

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

# use time::Weekday;
# use time_macros::date;
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)
);

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

# use time::Weekday;
# use time_macros::date;
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)
);

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

# use time::Weekday;
# use time_macros::date;
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)
);

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

# use time::Weekday;
# use time_macros::date;
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)
);

const fn iter_to(self, end: Self) -> DateIter

Create an iterator of dates from self to end inclusive.

# use time_macros::date;
let mut iter = date!(2019-01-01).iter_to(date!(2019-01-03));
assert_eq!(iter.next(), Some(date!(2019-01-01)));
assert_eq!(iter.next(), Some(date!(2019-01-02)));
assert_eq!(iter.next(), Some(date!(2019-01-03)));
assert_eq!(iter.next(), None);

const fn to_julian_day(self) -> i32

Get the Julian day for the date.

# use time_macros::date;
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);

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

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

# use time::{Date, ext::NumericalDuration};
# use time_macros::date;
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.

# use time::{Date, ext::NumericalDuration};
# use time_macros::date;
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))
);

const fn checked_add_std(self, duration: StdDuration) -> Option<Self>

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

# use time::{Date, ext::NumericalStdDuration};
# use time_macros::date;
assert_eq!(Date::MAX.checked_add_std(1.std_days()), None);
assert_eq!(
    date!(2020-12-31).checked_add_std(2.std_days()),
    Some(date!(2021-01-02))
);

Note

This function only takes whole days into account.

# use time::{Date, ext::NumericalStdDuration};
# use time_macros::date;
assert_eq!(Date::MAX.checked_add_std(23.std_hours()), Some(Date::MAX));
assert_eq!(
    date!(2020-12-31).checked_add_std(23.std_hours()),
    Some(date!(2020-12-31))
);
assert_eq!(
    date!(2020-12-31).checked_add_std(47.std_hours()),
    Some(date!(2021-01-01))
);

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

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

# use time::{Date, ext::NumericalDuration};
# use time_macros::date;
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.

# use time::{Date, ext::NumericalDuration};
# use time_macros::date;
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))
);

const fn checked_sub_std(self, duration: StdDuration) -> Option<Self>

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

# use time::{Date, ext::NumericalStdDuration};
# use time_macros::date;
assert_eq!(Date::MIN.checked_sub_std(1.std_days()), None);
assert_eq!(
    date!(2020-12-31).checked_sub_std(2.std_days()),
    Some(date!(2020-12-29))
);

Note

This function only takes whole days into account.

# use time::{Date, ext::NumericalStdDuration};
# use time_macros::date;
assert_eq!(Date::MIN.checked_sub_std(23.std_hours()), Some(Date::MIN));
assert_eq!(
    date!(2020-12-31).checked_sub_std(23.std_hours()),
    Some(date!(2020-12-31))
);
assert_eq!(
    date!(2020-12-31).checked_sub_std(47.std_hours()),
    Some(date!(2020-12-30))
);

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

Computes self + duration, saturating value on overflow.

# use time::{Date, ext::NumericalDuration};
# use time_macros::date;
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.

# use time::ext::NumericalDuration;
# use time_macros::date;
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)
);

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

Computes self - duration, saturating value on overflow.

# use time::{Date, ext::NumericalDuration};
# use time_macros::date;
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.

# use time::ext::NumericalDuration;
# use time_macros::date;
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)
);

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

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

# use time_macros::date;
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

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

Replace the month of the year.

# use time_macros::date;
# use time::Month;
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

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

Replace the day of the month.

# use time_macros::date;
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

const fn replace_ordinal(self, ordinal: u16) -> Result<Self, ComponentRange>

Replace the day of the year.

# use time_macros::date;
assert_eq!(date!(2022-049).replace_ordinal(1), Ok(date!(2022-001)));
assert!(date!(2022-049).replace_ordinal(0).is_err()); // 0 isn't a valid ordinal
assert!(date!(2022-049).replace_ordinal(366).is_err()); // 2022 isn't a leap year

Trait Implementations

impl Add<Duration> for Date

type Output = Date;
fn add(self, duration: StdDuration) -> Self::Output

Panics

This may panic if an overflow occurs.

impl Add<SignedDuration> for Date

type Output = Date;
fn add(self, duration: SignedDuration) -> Self::Output

Panics

This may panic if an overflow occurs.

impl AddAssign<Duration> for Date

fn add_assign(&mut self, rhs: StdDuration)

Panics

This may panic if an overflow occurs.

impl AddAssign<SignedDuration> for Date

fn add_assign(&mut self, rhs: SignedDuration)

Panics

This may panic if an overflow occurs.

impl Clone for Date

fn clone(&self) -> Self

impl Copy for Date

impl Debug for Date

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

impl Display for Date

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

impl Eq for Date

impl Hash for Date

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

impl Ord for Date

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

impl PartialEq for Date

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

impl PartialOrd for Date

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

impl SmartDisplay for Date

type Metadata = ();
fn metadata(&self, FormatterOptions) -> Metadata<'_, Self>
fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl StructuralPartialEq for Date

impl Sub for Date

type Output = SignedDuration;
fn sub(self, other: Self) -> Self::Output

impl Sub<Duration> for Date

type Output = Date;
fn sub(self, duration: StdDuration) -> Self::Output

Panics

This may panic if an overflow occurs.

impl Sub<SignedDuration> for Date

type Output = Date;
fn sub(self, duration: SignedDuration) -> Self::Output

Panics

This may panic if an overflow occurs.

impl SubAssign<Duration> for Date

fn sub_assign(&mut self, rhs: StdDuration)

Panics

This may panic if an overflow occurs.

impl SubAssign<SignedDuration> for Date

fn sub_assign(&mut self, rhs: SignedDuration)

Panics

This may panic if an overflow occurs.

Auto Trait Implementations

impl Freeze for Date

impl RefUnwindSafe for Date

impl Send for Date

impl Sync for Date

impl Unpin for Date

impl UnsafeUnpin for Date

impl UnwindSafe for Date

Blanket Implementations

impl<T> Any for Date where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Date where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Date where T: ?Sized,

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

impl<T> CloneToUninit for Date where T: Clone,

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

impl<T> From<T> for Date

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Date where T: Clone,

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

impl<T> ToString for Date where T: Display + ?Sized,

fn to_string(&self) -> String

impl<T, U> Into<U> for Date where U: From<T>,

fn into(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<U> for Date where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for Date where U: TryFrom<T>,

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