Struct time::Date [−][src]
pub struct Date { /* fields omitted */ }
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
The minimum valid Date
.
The value of this may vary depending on the feature flags enabled.
The maximum valid Date
.
The value of this may vary depending on the feature flags enabled.
pub 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>
pub 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.
RunCreate 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)));
RunGet 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);
RunGet the month.
assert_eq!(date!(2019 - 01 - 01).month(), Month::January);
assert_eq!(date!(2019 - 12 - 31).month(), Month::December);
RunGet 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);
RunGet 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);
RunGet 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);
RunGet 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);
RunGet 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);
RunGet the year, month, and day.
assert_eq!(
date!(2019 - 01 - 01).to_calendar_date(),
(2019, Month::January, 1)
);
RunGet the year and ordinal day number.
assert_eq!(date!(2019 - 01 - 01).to_ordinal_date(), (2019, 1));
RunGet 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));
RunGet 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);
RunGet 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);
RunGet 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);
RunGet 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);
RunMethods to add a Time
component, resulting in a 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));
RunCreate 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),
);
Runpub 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());
Runpub 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());
Runpub 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());
Runpub 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());
Runpub fn format_into(
self,
output: &mut impl Write,
format: &impl Formattable
) -> Result<usize, Format>
This is supported on crate feature formatting
only.
pub fn format_into(
self,
output: &mut impl Write,
format: &impl Formattable
) -> Result<usize, Format>
formatting
only.Format the Date
using the provided format description.
This is supported on crate feature formatting
only.
formatting
only.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");
RunThis is supported on crate feature parsing
only.
parsing
only.Parse a Date
from the input using the provided format
description.
let format = format_description::parse("[year]-[month]-[day]")?;
assert_eq!(Date::parse("2020-01-02", &format)?, date!(2020 - 01 - 02));
RunTrait Implementations
Performs the +=
operation. Read more
Performs the +=
operation. Read more
Deserialize this value from the given Serde deserializer. Read more
Generate a random value of T
, using rng
as the source of randomness.
Create an iterator that generates random values of T
, using rng
as
the source of randomness. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
Performs the -=
operation. Read more
Performs the -=
operation. Read more
Auto Trait Implementations
impl RefUnwindSafe for Date
impl UnwindSafe for Date
Blanket Implementations
Mutably borrows from an owned value. Read more