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.

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: cvengler

library/std/src/time.rs

@@ -511,6 +511,46 @@ 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);
+    /// ```
+    #[unstable(feature = "time_systemtime_limits", issue = "none")]
+    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.
+    ///
+    /// # 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);
+    /// ```
+    #[unstable(feature = "time_systemtime_limits", issue = "none")]
+    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());
+}