Struct time::Date

source · 
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§

source§

impl Date

source

pub const MIN: Self = _

The minimum valid Date.

The value of this may vary depending on the feature flags enabled.

source

pub const MAX: Self = _

The maximum valid Date.

The value of this may vary depending on the feature flags enabled.

source

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

assert!(Date::from_calendar_date(2019, Month::January, 1).is_ok());
assert!(Date::from_calendar_date(2019, Month::December, 31).is_ok());
Run
assert!(Date::from_calendar_date(2019, Month::February, 29).is_err()); // 2019 isn't a leap year.
Run
source

pub const fn from_ordinal_date( year: i32, ordinal: u16 ) -> Result<Self, ComponentRange>

Attempt to create a Date from the year and ordinal day number.

assert!(Date::from_ordinal_date(2019, 1).is_ok());
assert!(Date::from_ordinal_date(2019, 365).is_ok());
Run
assert!(Date::from_ordinal_date(2019, 366).is_err()); // 2019 isn't a leap year.
Run
source

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());
Run
assert!(Date::from_iso_week_date(2019, 53, Monday).is_err()); // 2019 doesn't have 53 weeks.
Run
source

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
Run
source

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
Run
source

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
Run
source§

impl Date

Methods to add a Time component, resulting in a PrimitiveDateTime.

source

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

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),
);
Run
source

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

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

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

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());
Run
source§

impl Date

source

pub fn format_into( self, output: &mut impl Write, format: &impl Formattable + ?Sized ) -> Result<usize, Format>

Format the Date using the provided format description.

source

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");
Run
source§

impl Date

source

pub fn parse( input: &str, description: &impl Parsable + ?Sized ) -> Result<Self, Parse>

Parse a Date from the input using the provided format description.

let format = format_description!("[year]-[month]-[day]");
assert_eq!(Date::parse("2020-01-02", &format)?, date!(2020 - 01 - 02));
Run

Trait Implementations§

source§

impl Add<Duration> for Date

§

type Output = Date

The resulting type after applying the + operator.
source§

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

Performs the + operation. Read more
source§

impl Add<Duration> for Date

§

type Output = Date

The resulting type after applying the + operator.
source§

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

Performs the + operation. Read more
source§

impl AddAssign<Duration> for Date

source§

fn add_assign(&mut self, rhs: StdDuration)

Performs the += operation. Read more
source§

impl AddAssign<Duration> for Date

source§

fn add_assign(&mut self, rhs: Duration)

Performs the += operation. Read more
source§

impl Clone for Date

source§

fn clone(&self) -> Date

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Date

source§

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

Formats the value using the given formatter. Read more
source§

impl Display for Date

source§

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

Formats the value using the given formatter. Read more
source§

impl Hash for Date

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl Ord for Date

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval. Read more
source§

impl PartialEq<Date> for Date

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl PartialOrd<Date> for Date

source§

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 · source§

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 · source§

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
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

impl Sub<Date> for Date

§

type Output = Duration

The resulting type after applying the - operator.
source§

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

Performs the - operation. Read more
source§

impl Sub<Duration> for Date

§

type Output = Date

The resulting type after applying the - operator.
source§

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

Performs the - operation. Read more
source§

impl Sub<Duration> for Date

§

type Output = Date

The resulting type after applying the - operator.
source§

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

Performs the - operation. Read more
source§

impl SubAssign<Duration> for Date

source§

fn sub_assign(&mut self, rhs: StdDuration)

Performs the -= operation. Read more
source§

impl SubAssign<Duration> for Date

source§

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation. Read more
source§

impl TryFrom<Parsed> for Date

§

type Error = TryFromParsed

The type returned in the event of a conversion error.
source§

fn try_from(parsed: Parsed) -> Result<Self, Self::Error>

Performs the conversion.
source§

impl Copy for Date

source§

impl Eq for Date

source§

impl StructuralEq for Date

source§

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§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

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

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

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

Performs the conversion.