logo

Struct time::Date

source · []
pub struct Date { /* private fields */ }
Expand description

Calendar date.

Years between -100_000 and +100_000 inclusive are guaranteed to be representable. Any values outside this range may have incidental support that can change at any time without notice. If you need support outside this range, please file an issue with your use case.

Implementations

Attempt to create a Date from the year, month, and day.

assert!(Date::try_from_ymd(2019, 1, 1).is_ok());
assert!(Date::try_from_ymd(2019, 12, 31).is_ok());

Returns None if the date is not valid.

assert!(Date::try_from_ymd(2019, 2, 29).is_err()); // 2019 isn't a leap year.

This function is const fn when using rustc >= 1.46.

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

assert!(Date::try_from_yo(2019, 1).is_ok());
assert!(Date::try_from_yo(2019, 365).is_ok());

Returns None if the date is not valid.

assert!(Date::try_from_yo(2019, 366).is_err()); // 2019 isn't a leap year.

This function is const fn when using rustc >= 1.46.

Attempt to create a Date from the ISO year, week, and weekday.

assert!(Date::try_from_iso_ywd(2019, 1, Monday).is_ok());
assert!(Date::try_from_iso_ywd(2019, 1, Tuesday).is_ok());
assert!(Date::try_from_iso_ywd(2020, 53, Friday).is_ok());

Returns None if the week is not valid.

assert!(Date::try_from_iso_ywd(2019, 53, Monday).is_err()); // 2019 doesn't have 53 weeks.

This function is const fn when using rustc >= 1.46.

👎 Deprecated since 0.2.7:

This method returns a value that assumes an offset of UTC.

Create a Date representing the current date.

assert!(Date::today().year() >= 2019);

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

This function is const fn when using rustc >= 1.46.

Get the month. If fetching both the month and day, it is more efficient to use Date::month_day.

The returned value will always be in the range 1..=12.

assert_eq!(date!(2019-01-01).month(), 1);
assert_eq!(date!(2019-12-31).month(), 12);

This function is const fn when using rustc >= 1.46.

Get the day of the month. If fetching both the month and day, it is more efficient to use Date::month_day.

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

This function is const fn when using rustc >= 1.46.

Get the month and day. This is more efficient than fetching the components individually.

The month component will always be in the range 1..=12; the day component in 1..=31.

assert_eq!(date!(2019-01-01).month_day(), (1, 1));
assert_eq!(date!(2019-12-31).month_day(), (12, 31));

This function is const fn when using rustc >= 1.46.

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

This function is const fn when using rustc >= 1.46.

Get the ISO 8601 year and week number.

assert_eq!(date!(2019-01-01).iso_year_week(), (2019, 1));
assert_eq!(date!(2019-10-04).iso_year_week(), (2019, 40));
assert_eq!(date!(2020-01-01).iso_year_week(), (2020, 1));
assert_eq!(date!(2020-12-31).iso_year_week(), (2020, 53));
assert_eq!(date!(2021-01-01).iso_year_week(), (2020, 53));

This function is const fn when using rustc >= 1.46.

Get the ISO week number.

The returned value will always be in the range 1..=53.

assert_eq!(date!(2019-01-01).week(), 1);
assert_eq!(date!(2019-10-04).week(), 40);
assert_eq!(date!(2020-01-01).week(), 1);
assert_eq!(date!(2020-12-31).week(), 53);
assert_eq!(date!(2021-01-01).week(), 53);

This function is const fn when using rustc >= 1.46.

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

This function is const fn when using rustc >= 1.46.

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

This function is const fn when using rustc >= 1.46.

Get the year, month, and day.

assert_eq!(date!(2019-01-01).as_ymd(), (2019, 1, 1));

This function is const fn when using rustc >= 1.46.

Get the year and ordinal day number.

assert_eq!(date!(2019-01-01).as_yo(), (2019, 1));

This function is const fn when using rustc >= 1.46.

Get the weekday.

This current uses Zeller’s congruence internally.

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

Get the next calendar date.

assert_eq!(date!(2019-01-01).next_day(), date!(2019-01-02));
assert_eq!(date!(2019-01-31).next_day(), date!(2019-02-01));
assert_eq!(date!(2019-12-31).next_day(), date!(2020-01-01));

Get the previous calendar date.

assert_eq!(date!(2019-01-02).previous_day(), date!(2019-01-01));
assert_eq!(date!(2019-02-01).previous_day(), date!(2019-01-31));
assert_eq!(date!(2020-01-01).previous_day(), date!(2019-12-31));

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).julian_day(), 0);
assert_eq!(date!(2000-01-01).julian_day(), 2_451_545);
assert_eq!(date!(2019-01-01).julian_day(), 2_458_485);
assert_eq!(date!(2019-12-31).julian_day(), 2_458_849);

This function is const fn when using rustc >= 1.46.

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),
    date!(-4713-11-24)
);
assert_eq!(Date::from_julian_day(2_451_545), date!(2000-01-01));
assert_eq!(Date::from_julian_day(2_458_485), date!(2019-01-01));
assert_eq!(Date::from_julian_day(2_458_849), date!(2019-12-31));

Methods 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(),
    date!(1970-01-01).with_time(time!(0:00))
);

Create a PrimitiveDateTime using the existing date and the provided Time.

assert_eq!(
    date!(1970-01-01).with_time(time!(0:00)),
    date!(1970-01-01).midnight(),
);

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970-01-01).try_with_hms(0, 0, 0).is_ok());
assert!(date!(1970-01-01).try_with_hms(24, 0, 0).is_err());

This function is const fn when using rustc >= 1.46.

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970-01-01).try_with_hms_milli(0, 0, 0, 0).is_ok());
assert!(date!(1970-01-01).try_with_hms_milli(24, 0, 0, 0).is_err());

This function is const fn when using rustc >= 1.46.

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970-01-01)
    .try_with_hms_micro(0, 0, 0, 0)
    .is_ok());
assert!(date!(1970-01-01)
    .try_with_hms_micro(24, 0, 0, 0)
    .is_err());

This function is const fn when using rustc >= 1.46.

Attempt to create a PrimitiveDateTime using the existing date and the provided time.

assert!(date!(1970-01-01).try_with_hms_nano(0, 0, 0, 0).is_ok());
assert!(date!(1970-01-01).try_with_hms_nano(24, 0, 0, 0).is_err());

This function is const fn when using rustc >= 1.46.

Methods that allow formatting the Date.

Format the Date using the provided string.

assert_eq!(date!(2019-01-02).format("%Y-%m-%d"), "2019-01-02");

Format the Date using the provided string.

assert_eq!(date!(2019-01-02).lazy_format("%Y-%m-%d").to_string(), "2019-01-02");

Attempt to parse a Date using the provided string.

assert_eq!(
    Date::parse("2019-01-02", "%F"),
    Ok(date!(2019-01-02))
);
assert_eq!(
    Date::parse("2019-002", "%Y-%j"),
    Ok(date!(2019-002))
);
assert_eq!(
    Date::parse("2019-W01-3", "%G-W%V-%u"),
    Ok(date!(2019-W01-3))
);

Trait Implementations

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Formats the value using the given formatter. Read more

Feeds this value into the given Hasher. Read more

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

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

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

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

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

Performs the -= operation. Read more

Performs the -= operation. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The resulting type after obtaining ownership.

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

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

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

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.