pub struct Date { /* private fields */ }
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.
Implementations
sourceimpl 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>
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());
Runassert!(Date::from_iso_week_date(2019, 53, Monday).is_err()); // 2019 doesn't have 53 weeks.
Runsourcepub 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.
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)));
Runsourcepub const fn year(self) -> i32
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);
Runsourcepub const fn month(self) -> Month
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);
Runsourcepub const fn day(self) -> u8
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);
Runsourcepub const fn ordinal(self) -> u16
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);
Runsourcepub 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
.
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);
Runsourcepub 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
.
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);
Runsourcepub 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
.
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);
Runsourcepub const fn to_calendar_date(self) -> (i32, Month, u8)
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)
);
Runsourcepub const fn to_ordinal_date(self) -> (i32, u16)
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));
Runsourcepub 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));
Runsourcepub 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);
Runsourcepub const fn next_day(self) -> Option<Self>
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);
Runsourcepub const fn previous_day(self) -> Option<Self>
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);
Runsourcepub 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.
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);
Runsourcepub 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))
);
RunNote
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))
);
Runsourcepub 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))
);
RunNote
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))
);
Runsourcepub 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)
);
RunNote
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)
);
Runsourcepub 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)
);
RunNote
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)
);
Runsourcepub 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.
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
Runsourcepub const fn replace_month(self, month: Month) -> Result<Self, ComponentRange>
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
Runsourcepub const fn replace_day(self, day: u8) -> Result<Self, ComponentRange>
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
Runsourceimpl 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.
assert_eq!(date!(1970-01-01).midnight(), datetime!(1970-01-01 0:00));
Runsourcepub 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
.
assert_eq!(
date!(1970-01-01).with_time(time!(0:00)),
datetime!(1970-01-01 0:00),
);
Runsourcepub 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.
assert!(date!(1970 - 01 - 01).with_hms(0, 0, 0).is_ok());
assert!(date!(1970 - 01 - 01).with_hms(24, 0, 0).is_err());
Runsourcepub 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.
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());
Runsourcepub 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.
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());
Runsourcepub 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.
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());
Runsourceimpl 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.
let format = format_description::parse("[year]-[month]-[day]")?;
assert_eq!(date!(2020 - 01 - 02).format(&format)?, "2020-01-02");
RunTrait Implementations
sourceimpl AddAssign<Duration> for Date
impl AddAssign<Duration> for Date
sourcefn add_assign(&mut self, rhs: Duration)
fn add_assign(&mut self, rhs: Duration)
Performs the +=
operation. Read more
sourceimpl AddAssign<Duration> for Date
impl AddAssign<Duration> for Date
sourcefn add_assign(&mut self, rhs: StdDuration)
fn add_assign(&mut self, rhs: StdDuration)
Performs the +=
operation. Read more
sourceimpl<'a> Deserialize<'a> for Date
impl<'a> Deserialize<'a> for Date
sourcefn deserialize<D: Deserializer<'a>>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D: Deserializer<'a>>(deserializer: D) -> Result<Self, D::Error>
Deserialize this value from the given Serde deserializer. Read more
sourceimpl Ord for Date
impl Ord for Date
sourceimpl PartialOrd<Date> for Date
impl PartialOrd<Date> for Date
sourcefn partial_cmp(&self, other: &Date) -> Option<Ordering>
fn partial_cmp(&self, other: &Date) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
1.0.0 · sourcefn lt(&self, other: &Rhs) -> bool
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
sourceimpl SubAssign<Duration> for Date
impl SubAssign<Duration> for Date
sourcefn sub_assign(&mut self, rhs: Duration)
fn sub_assign(&mut self, rhs: Duration)
Performs the -=
operation. Read more
sourceimpl SubAssign<Duration> for Date
impl SubAssign<Duration> for Date
sourcefn sub_assign(&mut self, rhs: StdDuration)
fn sub_assign(&mut self, rhs: StdDuration)
Performs the -=
operation. Read more
impl Copy for Date
impl Eq for Date
impl StructuralEq for Date
impl StructuralPartialEq for Date
Auto Trait Implementations
impl RefUnwindSafe for Date
impl Send for Date
impl Sync for Date
impl Unpin for Date
impl UnwindSafe for Date
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcepub fn to_owned(&self) -> T
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
sourcepub fn clone_into(&self, target: &mut T)
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more