time: Implement SystemTime::{MIN, MAX}

This commit introduces two new constants to SystemTime: `MIN` and `MAX`,
whose value 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.  Concrete implementation
depending upon the platform is done in later commits.

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.

Below are platform specifc notes:

# Hermit

The HermitOS implementation is more or less identitcal to the Unix one.

# sgx

The implementation uses a `Duration` to store the Unix time, thereby
implying `Duration::ZERO` and `Duration::MAX` as the limits.

# solid

The implementation uses a `time_t` to store the system time within a
single value (i.e. no dual secs/nanosecs handling), thereby implying its
`::MIN` and `::MAX` values as the respective boundaries.

# UEFI

UEFI has a weird way to store times, i.e. a very complicated struct.
The standard proclaims "1900-01-01T00:00:00+0000" to be the lowest
possible value and `MAX_UEFI_TIME` is already present for the upper
limit.

# Windows

Windows is weird.  The Win32 documentation makes no statement on a
maximum value here.  Next to this, there are two conflicting types:
`SYSTEMTIME` and `FILETIME`.  Rust's Standard Library uses `FILETIME`,
whose limit will (probably) be `i64::MAX` packed into two integers.
However, `SYSTEMTIME` has a lower-limit.

# xous

It is similar to sgx in the sense of using a `Duration`.

# unsupported

Unsupported platforms store a `SystemTime` in a `Duration`, just like
sgx, thereby implying `Duration::ZERO` and `Duration::MAX` as the
respective limits.

Author: cvengler

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

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());
+}