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

Add SystemTime::{MIN, MAX}

Accepted ACP: <rust-lang/libs-team#692>
Tracking Issue: <#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:
* #100141
* #133525
* #105762
* #71224
* #45448
* #52555

Author: ChrisDenton

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,23 @@ 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,
+    })
+    .unwrap();
+
     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 = SystemTime(Duration::MAX);
+
+    pub const MIN: SystemTime = 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();
@@ -101,8 +111,13 @@ impl SystemTime {
     }
 
     pub fn checked_sub_duration(&self, other: &Duration) -> Option<SystemTime> {
-        let intervals = self.intervals().checked_sub(checked_dur2intervals(other)?)?;
-        Some(SystemTime::from_intervals(intervals))
+        // Windows does not support times before 1601, hence why we don't
+        // support negatives. In order to tackle this, we try to convert the
+        // resulting value into an u64, which should obviously fail in the case
+        // that the value is below zero.
+        let intervals: u64 =
+            self.intervals().checked_sub(checked_dur2intervals(other)?)?.try_into().ok()?;
+        Some(SystemTime::from_intervals(intervals as i64))
     }
 }
 

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,83 @@ 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 of a [`Duration`], whose value is greater
+    /// than or equal to the time precision of the operating system, 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 one second will already fail ...
+    /// //
+    /// // Keep in mind that this in fact may succeed, if the Duration is
+    /// // smaller than the time precision of the operating system, which
+    /// // happens to be 1ns on most operating systems, with Windows being the
+    /// // notable exception by using 100ns, hence why this example uses 1s.
+    /// assert_eq!(SystemTime::MAX.checked_add(Duration::new(1, 0)), 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 of a [`Duration`] from, whose value is
+    /// greater than or equal to the time precision of the operating system, to
+    /// [`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 one second will already fail.
+    /// //
+    /// // Keep in mind that this in fact may succeed, if the Duration is
+    /// // smaller than the time precision of the operating system, which
+    /// // happens to be 1ns on most operating systems, with Windows being the
+    /// // notable exception by using 100ns, hence why this example uses 1s.
+    /// assert_eq!(SystemTime::MIN.checked_sub(Duration::new(1, 0)), 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
@@ -588,6 +665,9 @@ impl SystemTime {
     /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
     /// otherwise.
+    ///
+    /// In the case that the `duration` is smaller than the time precision of the operating
+    /// system, `Some(self)` will be returned.
     #[stable(feature = "time_checked_add", since = "1.34.0")]
     pub fn checked_add(&self, duration: Duration) -> Option<SystemTime> {
         self.0.checked_add_duration(&duration).map(SystemTime)
@@ -596,6 +676,9 @@ impl SystemTime {
     /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
     /// otherwise.
+    ///
+    /// In the case that the `duration` is smaller than the time precision of the operating
+    /// system, `Some(self)` will be returned.
     #[stable(feature = "time_checked_add", since = "1.34.0")]
     pub fn checked_sub(&self, duration: Duration) -> Option<SystemTime> {
         self.0.checked_sub_duration(&duration).map(SystemTime)

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,34 @@ 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() {
+    #[cfg(not(target_os = "windows"))]
+    /// Most (all?) non-Windows systems have nanosecond precision.
+    const MIN_INTERVAL: Duration = Duration::new(0, 1);
+    #[cfg(target_os = "windows")]
+    /// Windows' time precision is at 100ns.
+    const MIN_INTERVAL: Duration = Duration::new(0, 100);
+
+    // 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 ± the lowest time precision.
+    assert!(SystemTime::MAX.checked_add(MIN_INTERVAL).is_none());
+    assert!(SystemTime::MAX.checked_sub(MIN_INTERVAL).is_some());
+    assert!(SystemTime::MIN.checked_add(MIN_INTERVAL).is_some());
+    assert!(SystemTime::MIN.checked_sub(MIN_INTERVAL).is_none());
+}