Struct Date 

pub struct Date(pub Date);

An RFC 3339 full-date (YYYY-MM-DD), the wire form of OpenAPI’s format: date.

Tuple Fields

0: Date

Implementations

impl Date

pub fn into_inner(self) -> Date

The wrapped time value.

Methods from Deref<Target = Date>

pub 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 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 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 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 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 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 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 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 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 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 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 fn next_day(self) -> Option<Date>

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 fn previous_day(self) -> Option<Date>

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 fn next_occurrence(self, weekday: Weekday) -> Date

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 fn prev_occurrence(self, weekday: Weekday) -> Date

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 fn nth_next_occurrence(self, weekday: Weekday, n: u8) -> Date

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 fn nth_prev_occurrence(self, weekday: Weekday, n: u8) -> Date

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 fn iter_to(self, end: Date) -> DateIter

Create an iterator of dates from self to end inclusive.

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

pub fn to_julian_day(self) -> i32

Get the Julian day for the 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);

pub fn checked_add(self, duration: SignedDuration) -> Option<Date>

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 fn checked_add_std(self, duration: Duration) -> Option<Date>

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

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.

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

pub fn checked_sub(self, duration: SignedDuration) -> Option<Date>

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 fn checked_sub_std(self, duration: Duration) -> Option<Date>

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

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.

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

pub fn saturating_add(self, duration: SignedDuration) -> Date

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 fn saturating_sub(self, duration: SignedDuration) -> Date

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 fn replace_year(self, year: i32) -> Result<Date, 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 fn replace_month(self, month: Month) -> Result<Date, 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 fn replace_day(self, day: u8) -> Result<Date, 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

pub fn replace_ordinal(self, ordinal: u16) -> Result<Date, ComponentRange>

Replace the day of the year.

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

pub fn midnight(self) -> PlainDateTime

Create a PlainDateTime 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 fn with_time(self, time: Time) -> PlainDateTime

Create a PlainDateTime 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 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.

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

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

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

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

pub fn format_into( self, output: &mut (impl Write + ?Sized), 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_borrowed::<3>("[year]-[month]-[day]")?;
assert_eq!(date!(2020-01-02).format(&format)?, "2020-01-02");

Trait Implementations

impl Clone for Date

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Date

impl Debug for Date

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

Formats the value using the given formatter.

impl Deref for Date

type Target = Date

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Date

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de> Deserialize<'de> for Date

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Date

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

YYYY-MM-DD, matching Serialize for the reason given on DateTime’s Display, with the same fallback for a year RFC 3339’s four-digit full-date cannot express.

impl Eq for Date

impl From<Date> for Date

fn from(value: Date) -> Self

Converts to this type from the input type.

impl From<Date> for Date

fn from(value: Date) -> Self

Converts to this type from the input type.

impl FromStr for Date

fn from_str(text: &str) -> Result<Self, Self::Err>

Parses exactly YYYY-MM-DD. The length and separator positions are checked first so that a longer string (an accidental full date-time, say) is rejected rather than silently truncated to its date part.

type Err = ParseError

The associated error which can be returned from parsing.

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: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Date

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

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Date

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

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Date

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Date