impl Date

const fn midnight(self: Self) -> PrimitiveDateTime

Create a PrimitiveDateTime 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: Self, time: Time) -> PrimitiveDateTime

Create a PrimitiveDateTime 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: Self, hour: u8, minute: u8, second: u8) -> Result<PrimitiveDateTime, ComponentRange>

Attempt to create a PrimitiveDateTime 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: 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.

# 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: 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.

# 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: 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.

# 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 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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 to_julian_day(self: 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: Self, duration: Duration) -> 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: 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: Self, duration: Duration) -> 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: 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: Self, duration: Duration) -> 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: Self, duration: Duration) -> 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: 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: 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: 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: 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

impl Add for Date

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

Panics

This may panic if an overflow occurs.

impl Add for Date

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

Panics

This may panic if an overflow occurs.

impl AddAssign for Date

fn add_assign(self: &mut Self, rhs: Duration)

Panics

This may panic if an overflow occurs.

impl AddAssign for Date

fn add_assign(self: &mut Self, rhs: StdDuration)

Panics

This may panic if an overflow occurs.

impl Clone for Date

fn clone(self: &Self) -> Date

impl Copy for Date

impl Debug for Date

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

impl Display for Date

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

impl Eq for Date

impl Freeze for Date

impl Hash for Date

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

impl Ord for Date

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

impl PartialEq for Date

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

impl PartialOrd for Date

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

impl RefUnwindSafe for Date

impl Send for Date

impl SmartDisplay for Date

fn metadata(self: &Self, _: FormatterOptions) -> Metadata<'_, Self>

fn fmt_with_metadata(self: &Self, f: &mut Formatter<'_>, metadata: Metadata<'_, Self>) -> Result

impl StructuralPartialEq for Date

impl Sub for Date

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

Panics

This may panic if an overflow occurs.

impl Sub for Date

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

Panics

This may panic if an overflow occurs.

impl Sub for Date

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

impl SubAssign for Date

fn sub_assign(self: &mut Self, rhs: Duration)

Panics

This may panic if an overflow occurs.

impl SubAssign for Date

fn sub_assign(self: &mut Self, rhs: StdDuration)

Panics

This may panic if an overflow occurs.

impl Sync for Date

impl Unpin for Date

impl UnsafeUnpin for Date

impl UnwindSafe for Date

impl<T> Any for Date

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Date

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Date

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

impl<T> CloneToUninit for Date

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

impl<T> From for Date

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Date

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T> ToString for Date

fn to_string(self: &Self) -> String

impl<T, U> Into for Date

fn into(self: 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 for Date

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Date

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