Rollup merge of rust-lang#148825 - cvengler:time_systemtime_limits, r=ChrisDenton

Add SystemTime::{MIN, MAX}

Accepted ACP: <rust-lang/libs-team#692>
Tracking Issue: <rust-lang#149067>

---

This merge request introduces two new constants to `SystemTime`: `MIN` and `MAX`, whose values represent the maximum values for the respective data type, depending upon the platform.

Technically, this value is already obtainable during runtime with the following algorithm:
Use `SystemTime::UNIX_EPOCH` and call `checked_add` (or `checked_sub`) repeatedly with `Duration::new(0, 1)` on it, until it returns None.
Mathematically speaking, this algorithm will terminate after a finite amount of steps, yet it is impractical to run it, as it takes practically forever.

Besides, this commit also adds a unit test to verify those values represent the respective minimum and maximum, by letting a `checked_add` and `checked_sub` on it fail.

In the future, the hope of the authors lies within the creation of a `SystemTime::saturating_add` and `SystemTime::saturating_sub`, similar to the functions already present in `std::time::Duration`.
However, for those, these constants are crucially required, thereby this should be seen as the initial step towards this direction.
With this change, implementing these functions oneself outside the standard library becomes feasible in a portable manner for the first time.

This feature (and a related saturating version of `checked_{add, sub}` has been requested multiple times over the course of the past few years, most notably:
* rust-lang#100141
* rust-lang#133525
* rust-lang#105762
* rust-lang#71224
* rust-lang#45448
* rust-lang#52555

Author: JonathanBrouwer

library/std/src/sys/pal/hermit/time.rs

@@ -15,6 +15,10 @@ struct Timespec {
 }
 
 impl Timespec {
+    const MAX: Timespec = Self::new(i64::MAX, 1_000_000_000 - 1);
+
+    const MIN: Timespec = Self::new(i64::MIN, 0);
+
     const fn zero() -> Timespec {
         Timespec { t: timespec { tv_sec: 0, tv_nsec: 0 } }
     }
@@ -209,6 +213,10 @@ pub struct SystemTime(Timespec);
 pub const UNIX_EPOCH: SystemTime = SystemTime(Timespec::zero());
 
 impl SystemTime {
+    pub const MAX: SystemTime = SystemTime { t: Timespec::MAX };
+
+    pub const MIN: SystemTime = SystemTime { t: Timespec::MIN };
+
     pub fn new(tv_sec: i64, tv_nsec: i32) -> SystemTime {
         SystemTime(Timespec::new(tv_sec, tv_nsec))
     }

library/std/src/sys/pal/sgx/time.rs

@@ -28,6 +28,10 @@ impl Instant {
 }
 
 impl SystemTime {
+    pub const MAX: SystemTime = SystemTime(Duration::MAX);
+
+    pub const MIN: SystemTime = SystemTime(Duration::ZERO);
+
     pub fn now() -> SystemTime {
         SystemTime(usercalls::insecure_time())
     }

library/std/src/sys/pal/solid/time.rs

@@ -10,6 +10,10 @@ pub struct SystemTime(abi::time_t);
 pub const UNIX_EPOCH: SystemTime = SystemTime(0);
 
 impl SystemTime {
+    pub const MAX: SystemTime = SystemTime(abi::time_t::MAX);
+
+    pub const MIN: SystemTime = SystemTime(abi::time_t::MIN);
+
     pub fn now() -> SystemTime {
         let rtc = unsafe {
             let mut out = MaybeUninit::zeroed();

library/std/src/sys/pal/uefi/time.rs

@@ -70,6 +70,22 @@ impl Instant {
 }
 
 impl SystemTime {
+    pub const MAX: SystemTime = MAX_UEFI_TIME;
+
+    pub const MIN: SystemTime = SystemTime::from_uefi(r_efi::efi::Time {
+        year: 1900,
+        month: 1,
+        day: 1,
+        hour: 0,
+        minute: 0,
+        second: 0,
+        nanosecond: 0,
+        timezone: -1440,
+        daylight: 0,
+        pad1: 0,
+        pad2: 0,
+    });
+
     pub(crate) const fn from_uefi(t: r_efi::efi::Time) -> Option<Self> {
         match system_time_internal::from_uefi(&t) {
             Some(x) => Some(Self(x)),

library/std/src/sys/pal/unix/time.rs

@@ -30,6 +30,10 @@ pub(crate) struct Timespec {
 }
 
 impl SystemTime {
+    pub const MAX: SystemTime = SystemTime { t: Timespec::MAX };
+
+    pub const MIN: SystemTime = SystemTime { t: Timespec::MIN };
+
     #[cfg_attr(any(target_os = "horizon", target_os = "hurd"), allow(unused))]
     pub fn new(tv_sec: i64, tv_nsec: i64) -> Result<SystemTime, io::Error> {
         Ok(SystemTime { t: Timespec::new(tv_sec, tv_nsec)? })
@@ -62,6 +66,13 @@ impl fmt::Debug for SystemTime {
 }
 
 impl Timespec {
+    const MAX: Timespec = unsafe { Self::new_unchecked(i64::MAX, 1_000_000_000 - 1) };
+
+    // As described below, on Apple OS, dates before epoch are represented differently.
+    // This is not an issue here however, because we are using tv_sec = i64::MIN,
+    // which will cause the compatibility wrapper to not be executed at all.
+    const MIN: Timespec = unsafe { Self::new_unchecked(i64::MIN, 0) };
+
     const unsafe fn new_unchecked(tv_sec: i64, tv_nsec: i64) -> Timespec {
         Timespec { tv_sec, tv_nsec: unsafe { Nanoseconds::new_unchecked(tv_nsec as u32) } }
     }

library/std/src/sys/pal/unsupported/time.rs

@@ -27,6 +27,10 @@ impl Instant {
 }
 
 impl SystemTime {
+    pub const MAX: SystemTime = Duration::MAX;
+
+    pub const MIN: SystemTime = Duration::ZERO;
+
     pub fn now() -> SystemTime {
         panic!("time not implemented on this platform")
     }

library/std/src/sys/pal/windows/time.rs

@@ -64,6 +64,16 @@ impl Instant {
 }
 
 impl SystemTime {
+    pub const MAX: SystemTime = SystemTime {
+        t: c::FILETIME {
+            dwLowDateTime: (i64::MAX & 0xFFFFFFFF) as u32,
+            dwHighDateTime: (i64::MAX >> 32) as u32,
+        },
+    };
+
+    pub const MIN: SystemTime =
+        SystemTime { t: c::FILETIME { dwLowDateTime: 0, dwHighDateTime: 0 } };
+
     pub fn now() -> SystemTime {
         unsafe {
             let mut t: SystemTime = mem::zeroed();

library/std/src/sys/pal/xous/time.rs

@@ -35,6 +35,10 @@ impl Instant {
 }
 
 impl SystemTime {
+    pub const MAX: SystemTime = SystemTime(Duration::MAX);
+
+    pub const MIN: SystemTime = SystemTime(Duration::ZERO);
+
     pub fn now() -> SystemTime {
         let result = blocking_scalar(systime_server(), GetUtcTimeMs.into())
             .expect("failed to request utc time in ms");

library/std/src/time.rs

@@ -511,6 +511,69 @@ impl SystemTime {
     #[stable(feature = "assoc_unix_epoch", since = "1.28.0")]
     pub const UNIX_EPOCH: SystemTime = UNIX_EPOCH;
 
+    /// Represents the maximum value representable by [`SystemTime`] on this platform.
+    ///
+    /// This value differs a lot between platforms, but it is always the case
+    /// that any positive addition to [`SystemTime::MAX`] will fail.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// #![feature(time_systemtime_limits)]
+    /// use std::time::{Duration, SystemTime};
+    ///
+    /// // Adding zero will change nothing.
+    /// assert_eq!(SystemTime::MAX.checked_add(Duration::ZERO), Some(SystemTime::MAX));
+    ///
+    /// // But adding just 1ns will already fail.
+    /// assert_eq!(SystemTime::MAX.checked_add(Duration::new(0, 1)), None);
+    ///
+    /// // Utilize this for saturating arithmetic to improve error handling.
+    /// // In this case, we will use a certificate with a timestamp in the
+    /// // future as a practical example.
+    /// let configured_offset = Duration::from_secs(60 * 60 * 24);
+    /// let valid_after =
+    ///     SystemTime::now()
+    ///         .checked_add(configured_offset)
+    ///         .unwrap_or(SystemTime::MAX);
+    /// ```
+    #[unstable(feature = "time_systemtime_limits", issue = "149067")]
+    pub const MAX: SystemTime = SystemTime(time::SystemTime::MAX);
+
+    /// Represents the minimum value representable by [`SystemTime`] on this platform.
+    ///
+    /// This value differs a lot between platforms, but it is always the case
+    /// that any positive subtraction from [`SystemTime::MIN`] will fail.
+    ///
+    /// Depending on the platform, this may be either less than or equal to
+    /// [`SystemTime::UNIX_EPOCH`], depending on whether the operating system
+    /// supports the representation of timestamps before the Unix epoch or not.
+    /// However, it is always guaranteed that a [`SystemTime::UNIX_EPOCH`] fits
+    /// between a [`SystemTime::MIN`] and [`SystemTime::MAX`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(time_systemtime_limits)]
+    /// use std::time::{Duration, SystemTime};
+    ///
+    /// // Subtracting zero will change nothing.
+    /// assert_eq!(SystemTime::MIN.checked_sub(Duration::ZERO), Some(SystemTime::MIN));
+    ///
+    /// // But subtracting just 1ns will already fail.
+    /// assert_eq!(SystemTime::MIN.checked_sub(Duration::new(0, 1)), None);
+    ///
+    /// // Utilize this for saturating arithmetic to improve error handling.
+    /// // In this case, we will use a cache expiry as a practical example.
+    /// let configured_expiry = Duration::from_secs(60 * 3);
+    /// let expiry_threshold =
+    ///     SystemTime::now()
+    ///         .checked_sub(configured_expiry)
+    ///         .unwrap_or(SystemTime::MIN);
+    /// ```
+    #[unstable(feature = "time_systemtime_limits", issue = "149067")]
+    pub const MIN: SystemTime = SystemTime(time::SystemTime::MIN);
+
     /// Returns the system time corresponding to "now".
     ///
     /// # Examples

library/std/tests/time.rs

@@ -1,4 +1,5 @@
 #![feature(duration_constants)]
+#![feature(time_systemtime_limits)]
 
 use std::fmt::Debug;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
@@ -237,9 +238,27 @@ fn system_time_duration_since_max_range_on_unix() {
     let min = SystemTime::UNIX_EPOCH - (Duration::new(i64::MAX as u64 + 1, 0));
     let max = SystemTime::UNIX_EPOCH + (Duration::new(i64::MAX as u64, 999_999_999));
 
+    assert_eq!(min, SystemTime::MIN);
+    assert_eq!(max, SystemTime::MAX);
+
     let delta_a = max.duration_since(min).expect("duration_since overflow");
     let delta_b = min.duration_since(max).expect_err("duration_since overflow").duration();
 
     assert_eq!(Duration::MAX, delta_a);
     assert_eq!(Duration::MAX, delta_b);
 }
+
+#[test]
+fn system_time_max_min() {
+    // First, test everything with checked_* and Duration::ZERO.
+    assert_eq!(SystemTime::MAX.checked_add(Duration::ZERO), Some(SystemTime::MAX));
+    assert_eq!(SystemTime::MAX.checked_sub(Duration::ZERO), Some(SystemTime::MAX));
+    assert_eq!(SystemTime::MIN.checked_add(Duration::ZERO), Some(SystemTime::MIN));
+    assert_eq!(SystemTime::MIN.checked_sub(Duration::ZERO), Some(SystemTime::MIN));
+
+    // Now do the same again with checked_* but try by ± a single nanosecond.
+    assert!(SystemTime::MAX.checked_add(Duration::new(0, 1)).is_none());
+    assert!(SystemTime::MAX.checked_sub(Duration::new(0, 1)).is_some());
+    assert!(SystemTime::MIN.checked_add(Duration::new(0, 1)).is_some());
+    assert!(SystemTime::MIN.checked_sub(Duration::new(0, 1)).is_none());
+}