ACP: Add `Duration::{WEEK, DAY, HOUR, MINUTE}` associated constants

Proposal

Problem statement

For Duration, associated constants representing durations of one second, one millisecond, one microsecond, and one nanosecond are available as nightly-only experimental APIs. These durations can also be constructed from associated functions such as Duration::from_secs.

For Duration, associated functions are also provided to construct a Duration from weeks, days, hours, and minutes, such as Duration::from_hours. However, associated constants for representing one week, one day, one hour, or one minute are not provided.

Motivating examples or use cases

• Similar to rust-lang/rust#57391.
• Improve consistency with this.

assert_eq!(Duration::SECOND * 86400, Duration::from_days(1));
assert_eq!(Duration::DAY, Duration::from_days(1));

assert_eq!(Duration::SECOND * 21600, Duration::from_hours(6));
assert_eq!(Duration::HOUR * 6, Duration::from_hours(6));

Solution sketch

// core::time

impl Duration {
    /// The duration of one week.
    ///
    /// For this constant, one week is defined as 7 days, or 604,800 seconds.
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(duration_constants_heavy)]
    /// #![feature(duration_constructors)]
    /// use std::time::Duration;
    ///
    /// let week = Duration::WEEK;
    ///
    /// assert_eq!(week, Duration::from_weeks(1));
    /// assert_eq!(week.as_secs(), 604_800);
    /// assert_eq!(week.subsec_nanos(), 0);
    /// ```
    #[unstable(feature = "duration_constants_heavy", issue = "TBD")]
    // Also, #[unstable(feature = "duration_constructors", issue = "120301")]
    pub const WEEK: Duration = Duration::from_weeks(1);

    /// The duration of one day.
    ///
    /// For this constant, one day is defined as 24 hours, or 86,400 seconds.
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(duration_constants_heavy)]
    /// #![feature(duration_constructors)]
    /// use std::time::Duration;
    ///
    /// let day = Duration::DAY;
    ///
    /// assert_eq!(day, Duration::from_days(1));
    /// assert_eq!(day.as_secs(), 86400);
    /// assert_eq!(day.subsec_nanos(), 0);
    /// ```
    #[unstable(feature = "duration_constants_heavy", issue = "TBD")]
    // Also, #[unstable(feature = "duration_constructors", issue = "120301")]
    pub const DAY: Duration = Duration::from_days(1);

    /// The duration of one hour.
    ///
    /// For this constant, one hour is defined as 60 minutes, or 3,600 seconds.
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(duration_constants_heavy)]
    /// use std::time::Duration;
    ///
    /// let hour = Duration::HOUR;
    ///
    /// assert_eq!(hour, Duration::from_hours(1));
    /// assert_eq!(hour.as_secs(), 3600);
    /// assert_eq!(hour.subsec_nanos(), 0);
    /// ```
    #[unstable(feature = "duration_constants_heavy", issue = "TBD")]
    pub const HOUR: Duration = Duration::from_hours(1);

    /// The duration of one minute.
    ///
    /// For this constant, one minute is defined as 60 seconds.
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(duration_constants_heavy)]
    /// use std::time::Duration;
    ///
    /// let minute = Duration::MINUTE;
    ///
    /// assert_eq!(minute, Duration::from_mins(1));
    /// assert_eq!(minute.as_secs(), 60);
    /// assert_eq!(minute.subsec_nanos(), 0);
    /// ```
    #[unstable(feature = "duration_constants_heavy", issue = "TBD")]
    pub const MINUTE: Duration = Duration::from_mins(1);
}

If the duration_constructors feature (Duration::from_weeks and Duration::from_days) is abandoned without being stabilized, I don't think there is a need to add Duration::WEEK and Duration::DAY. This is because I think it lacks consistency to have corresponding associated constants without associated functions.

Duration represents a span of time, rather than a calendar date and time. So, I don't think there is any need to take DST or a leap second into account. I don't think that units of time larger than a week (such as a month or a year) can be defined as associated constants, because spans of these are variable.

Alternatives

We can use the existing associated constants, but readability is poor because the largest unit is Duration::SECOND.

assert_eq!(Duration::SECOND * 259_200, Duration::from_hours(72));
assert_eq!(Duration::HOUR * 72, Duration::from_hours(72));
assert_eq!(Duration::DAY * 3, Duration::from_hours(72));

While there are ways to use the existing associated functions, using associated constants instead makes working with Duration more ergonomic.

Links and related work

rust-lang/rust#57391

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

Start with the proposed core::time::Duration API and read the linked feature lifecycle and rust-lang/rust#57391 for context. The proposal is complete when the libs-api team reaches a decision on adding WEEK, DAY, HOUR, and MINUTE, including how they relate to the duration constructors.