pub struct Date {
value: NonZeroI32,
}
Expand description
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.
Fields§
§value: NonZeroI32
Bitpacked field containing both the year and ordinal.
Implementations§
source§impl Date
impl Date
sourcepub const MIN: Self = _
pub const MIN: Self = _
The minimum valid Date
.
The value of this may vary depending on the feature flags enabled.
sourcepub const MAX: Self = _
pub const MAX: Self = _
The maximum valid Date
.
The value of this may vary depending on the feature flags enabled.
sourcepub const fn from_calendar_date(
year: i32,
month: Month,
day: u8,
) -> Result<Self, ComponentRange>
pub const fn from_calendar_date( year: i32, month: Month, day: u8, ) -> Result<Self, ComponentRange>
sourcepub const fn from_ordinal_date(
year: i32,
ordinal: u16,
) -> Result<Self, ComponentRange>
pub const fn from_ordinal_date( year: i32, ordinal: u16, ) -> Result<Self, ComponentRange>
sourcepub const fn from_iso_week_date(
year: i32,
week: u8,
weekday: Weekday,
) -> Result<Self, ComponentRange>
pub const fn from_iso_week_date( year: i32, week: u8, weekday: Weekday, ) -> Result<Self, ComponentRange>
sourcepub const fn from_julian_day(julian_day: i32) -> Result<Self, ComponentRange>
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.
sourcepub(crate) const fn from_julian_day_unchecked(julian_day: i32) -> Self
pub(crate) const fn from_julian_day_unchecked(julian_day: i32) -> Self
Create a Date
from the Julian day.
This does not check the validity of the provided Julian day, and as such may result in an internally invalid value.
sourcepub(crate) const fn month_day(self) -> (Month, u8)
pub(crate) const fn month_day(self) -> (Month, u8)
Get the month and day. This is more efficient than fetching the components individually.
sourcepub(crate) const fn iso_year_week(self) -> (i32, u8)
pub(crate) const fn iso_year_week(self) -> (i32, u8)
Get the ISO 8601 year and week number.
sourcepub const fn iso_week(self) -> u8
pub const fn iso_week(self) -> u8
Get the ISO week number.
The returned value will always be in the range 1..=53
.
sourcepub const fn sunday_based_week(self) -> u8
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
.
sourcepub const fn monday_based_week(self) -> u8
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
.
sourcepub const fn to_calendar_date(self) -> (i32, Month, u8)
pub const fn to_calendar_date(self) -> (i32, Month, u8)
sourcepub const fn to_ordinal_date(self) -> (i32, u16)
pub const fn to_ordinal_date(self) -> (i32, u16)
sourcepub const fn to_iso_week_date(self) -> (i32, u8, Weekday)
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));
sourcepub const fn weekday(self) -> Weekday
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);
sourcepub const fn previous_day(self) -> Option<Self>
pub const fn previous_day(self) -> Option<Self>
Get the previous calendar date.
sourcepub const fn next_occurrence(self, weekday: Weekday) -> Self
pub const fn next_occurrence(self, weekday: Weekday) -> Self
sourcepub const fn prev_occurrence(self, weekday: Weekday) -> Self
pub const fn prev_occurrence(self, weekday: Weekday) -> Self
sourcepub const fn nth_next_occurrence(self, weekday: Weekday, n: u8) -> Self
pub const fn nth_next_occurrence(self, weekday: Weekday, n: u8) -> Self
sourcepub const fn nth_prev_occurrence(self, weekday: Weekday, n: u8) -> Self
pub const fn nth_prev_occurrence(self, weekday: Weekday, n: u8) -> Self
sourcepub const fn to_julian_day(self) -> i32
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.
sourcepub const fn checked_add(self, duration: Duration) -> Option<Self>
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))
);
sourcepub const fn checked_add_std(self, duration: StdDuration) -> Option<Self>
pub const fn checked_add_std(self, duration: StdDuration) -> Option<Self>
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.
sourcepub const fn checked_sub(self, duration: Duration) -> Option<Self>
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))
);
sourcepub const fn checked_sub_std(self, duration: StdDuration) -> Option<Self>
pub const fn checked_sub_std(self, duration: StdDuration) -> Option<Self>
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.
sourcepub(crate) const fn checked_next_occurrence(
self,
weekday: Weekday,
) -> Option<Self>
pub(crate) const fn checked_next_occurrence( self, weekday: Weekday, ) -> Option<Self>
Calculates the first occurrence of a weekday that is strictly later than a given Date
.
Returns None
if an overflow occurred.
sourcepub(crate) const fn checked_prev_occurrence(
self,
weekday: Weekday,
) -> Option<Self>
pub(crate) const fn checked_prev_occurrence( self, weekday: Weekday, ) -> Option<Self>
Calculates the first occurrence of a weekday that is strictly earlier than a given Date
.
Returns None
if an overflow occurred.
sourcepub(crate) const fn checked_nth_next_occurrence(
self,
weekday: Weekday,
n: u8,
) -> Option<Self>
pub(crate) const fn checked_nth_next_occurrence( self, weekday: Weekday, n: u8, ) -> Option<Self>
Calculates the n
th occurrence of a weekday that is strictly later than a given Date
.
Returns None
if an overflow occurred or if n == 0
.
sourcepub(crate) const fn checked_nth_prev_occurrence(
self,
weekday: Weekday,
n: u8,
) -> Option<Self>
pub(crate) const fn checked_nth_prev_occurrence( self, weekday: Weekday, n: u8, ) -> Option<Self>
Calculates the n
th occurrence of a weekday that is strictly earlier than a given Date
.
Returns None
if an overflow occurred or if n == 0
.
sourcepub const fn saturating_add(self, duration: Duration) -> Self
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.
sourcepub const fn saturating_sub(self, duration: Duration) -> Self
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.
sourcepub const fn replace_year(self, year: i32) -> Result<Self, ComponentRange>
pub const fn replace_year(self, year: i32) -> Result<Self, ComponentRange>
Replace the year. The month and day will be unchanged.
sourcepub const fn replace_month(self, month: Month) -> Result<Self, ComponentRange>
pub const fn replace_month(self, month: Month) -> Result<Self, ComponentRange>
sourcepub const fn replace_day(self, day: u8) -> Result<Self, ComponentRange>
pub const fn replace_day(self, day: u8) -> Result<Self, ComponentRange>
sourcepub const fn replace_ordinal(self, ordinal: u16) -> Result<Self, ComponentRange>
pub const fn replace_ordinal(self, ordinal: u16) -> Result<Self, ComponentRange>
source§impl Date
impl Date
Methods to add a Time
component, resulting in a PrimitiveDateTime
.
sourcepub const fn midnight(self) -> PrimitiveDateTime
pub const fn midnight(self) -> PrimitiveDateTime
Create a PrimitiveDateTime
using the existing date. The Time
component will be set
to midnight.
sourcepub const fn with_time(self, time: Time) -> PrimitiveDateTime
pub const fn with_time(self, time: Time) -> PrimitiveDateTime
Create a PrimitiveDateTime
using the existing date and the provided Time
.
sourcepub const fn with_hms(
self,
hour: u8,
minute: u8,
second: u8,
) -> Result<PrimitiveDateTime, ComponentRange>
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.
sourcepub const fn with_hms_milli(
self,
hour: u8,
minute: u8,
second: u8,
millisecond: u16,
) -> Result<PrimitiveDateTime, ComponentRange>
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.
sourcepub const fn with_hms_micro(
self,
hour: u8,
minute: u8,
second: u8,
microsecond: u32,
) -> Result<PrimitiveDateTime, ComponentRange>
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.
sourcepub const fn with_hms_nano(
self,
hour: u8,
minute: u8,
second: u8,
nanosecond: u32,
) -> Result<PrimitiveDateTime, ComponentRange>
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.
source§impl Date
impl Date
sourcepub fn format_into(
self,
output: &mut impl Write,
format: &(impl Formattable + ?Sized),
) -> Result<usize, Format>
pub fn format_into( self, output: &mut impl Write, format: &(impl Formattable + ?Sized), ) -> Result<usize, Format>
Format the Date
using the provided format description.
sourcepub fn format(
self,
format: &(impl Formattable + ?Sized),
) -> Result<String, Format>
pub fn format( self, format: &(impl Formattable + ?Sized), ) -> Result<String, Format>
Format the Date
using the provided format description.
Trait Implementations§
source§impl AddAssign<Duration> for Date
impl AddAssign<Duration> for Date
source§fn add_assign(&mut self, rhs: Duration)
fn add_assign(&mut self, rhs: Duration)
+=
operation. Read moresource§impl AddAssign<Duration> for Date
impl AddAssign<Duration> for Date
source§fn add_assign(&mut self, rhs: StdDuration)
fn add_assign(&mut self, rhs: StdDuration)
+=
operation. Read moresource§impl<'a> Deserialize<'a> for Date
impl<'a> Deserialize<'a> for Date
source§fn deserialize<D: Deserializer<'a>>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D: Deserializer<'a>>(deserializer: D) -> Result<Self, D::Error>
source§impl Ord for Date
impl Ord for Date
source§impl PartialOrd for Date
impl PartialOrd for Date
source§impl SmartDisplay for Date
impl SmartDisplay for Date
source§type Metadata = DateMetadata
type Metadata = DateMetadata
source§fn metadata(&self, _: FormatterOptions) -> Metadata<'_, Self>
fn metadata(&self, _: FormatterOptions) -> Metadata<'_, Self>
source§impl SubAssign<Duration> for Date
impl SubAssign<Duration> for Date
source§fn sub_assign(&mut self, rhs: Duration)
fn sub_assign(&mut self, rhs: Duration)
-=
operation. Read moresource§impl SubAssign<Duration> for Date
impl SubAssign<Duration> for Date
source§fn sub_assign(&mut self, rhs: StdDuration)
fn sub_assign(&mut self, rhs: StdDuration)
-=
operation. Read moreimpl Copy for Date
impl Eq for Date
impl StructuralPartialEq for Date
Auto Trait Implementations§
impl Freeze for Date
impl RefUnwindSafe for Date
impl Send for Date
impl Sync for Date
impl Unpin for Date
impl UnwindSafe for Date
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)