library/std/src/time.rs

   1 //! Temporal quantification.
   2 //!
   3 //! # Examples:
   4 //!
   5 //! There are multiple ways to create a new [`Duration`]:
   6 //!
   7 //! ```
   8 //! # use std::time::Duration;
   9 //! let five_seconds = Duration::from_secs(5);
  10 //! assert_eq!(five_seconds, Duration::from_millis(5_000));
  11 //! assert_eq!(five_seconds, Duration::from_micros(5_000_000));
  12 //! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000));
  13 //!
  14 //! let ten_seconds = Duration::from_secs(10);
  15 //! let seven_nanos = Duration::from_nanos(7);
  16 //! let total = ten_seconds + seven_nanos;
  17 //! assert_eq!(total, Duration::new(10, 7));
  18 //! ```
  19 //!
  20 //! Using [`Instant`] to calculate how long a function took to run:
  21 //!
  22 //! ```ignore (incomplete)
  23 //! let now = Instant::now();
  24 //!
  25 //! // Calling a slow function, it may take a while
  26 //! slow_function();
  27 //!
  28 //! let elapsed_time = now.elapsed();
  29 //! println!("Running slow_function() took {} seconds.", elapsed_time.as_secs());
  30 //! ```
  31
  32 #![stable(feature = "time", since = "1.3.0")]
  33
  34 mod monotonic;
  35 #[cfg(test)]
  36 mod tests;
  37
  38 use crate::error::Error;
  39 use crate::fmt;
  40 use crate::ops::{Add, AddAssign, Sub, SubAssign};
  41 use crate::sys::time;
  42 use crate::sys_common::FromInner;
  43
  44 #[stable(feature = "time", since = "1.3.0")]
  45 pub use core::time::Duration;
  46
  47 #[unstable(feature = "duration_checked_float", issue = "83400")]
  48 pub use core::time::FromFloatSecsError;
  49
  50 /// A measurement of a monotonically nondecreasing clock.
  51 /// Opaque and useful only with [`Duration`].
  52 ///
  53 /// Instants are always guaranteed to be no less than any previously measured
  54 /// instant when created, and are often useful for tasks such as measuring
  55 /// benchmarks or timing how long an operation takes.
  56 ///
  57 /// Note, however, that instants are **not** guaranteed to be **steady**. In other
  58 /// words, each tick of the underlying clock might not be the same length (e.g.
  59 /// some seconds may be longer than others). An instant may jump forwards or
  60 /// experience time dilation (slow down or speed up), but it will never go
  61 /// backwards.
  62 ///
  63 /// Instants are opaque types that can only be compared to one another. There is
  64 /// no method to get "the number of seconds" from an instant. Instead, it only
  65 /// allows measuring the duration between two instants (or comparing two
  66 /// instants).
  67 ///
  68 /// The size of an `Instant` struct may vary depending on the target operating
  69 /// system.
  70 ///
  71 /// Example:
  72 ///
  73 /// ```no_run
  74 /// use std::time::{Duration, Instant};
  75 /// use std::thread::sleep;
  76 ///
  77 /// fn main() {
  78 ///    let now = Instant::now();
  79 ///
  80 ///    // we sleep for 2 seconds
  81 ///    sleep(Duration::new(2, 0));
  82 ///    // it prints '2'
  83 ///    println!("{}", now.elapsed().as_secs());
  84 /// }
  85 /// ```
  86 ///
  87 /// # OS-specific behaviors
  88 ///
  89 /// An `Instant` is a wrapper around system-specific types and it may behave
  90 /// differently depending on the underlying operating system. For example,
  91 /// the following snippet is fine on Linux but panics on macOS:
  92 ///
  93 /// ```no_run
  94 /// use std::time::{Instant, Duration};
  95 ///
  96 /// let now = Instant::now();
  97 /// let max_nanoseconds = u64::MAX / 1_000_000_000;
  98 /// let duration = Duration::new(max_nanoseconds, 0);
  99 /// println!("{:?}", now + duration);
 100 /// ```
 101 ///
 102 /// # Underlying System calls
 103 /// Currently, the following system calls are being used to get the current time using `now()`:
 104 ///
 105 /// |  Platform |               System call                                            |
 106 /// |-----------|----------------------------------------------------------------------|
 107 /// | SGX       | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
 108 /// | UNIX      | [clock_gettime (Monotonic Clock)]                                    |
 109 /// | Darwin    | [mach_absolute_time]                                                 |
 110 /// | VXWorks   | [clock_gettime (Monotonic Clock)]                                    |
 111 /// | SOLID     | `get_tim`                                                            |
 112 /// | WASI      | [__wasi_clock_time_get (Monotonic Clock)]                            |
 113 /// | Windows   | [QueryPerformanceCounter]                                            |
 114 ///
 115 /// [QueryPerformanceCounter]: https://docs.microsoft.com/en-us/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter
 116 /// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time
 117 /// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode
 118 /// [__wasi_clock_time_get (Monotonic Clock)]: https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#clock_time_get
 119 /// [clock_gettime (Monotonic Clock)]: https://linux.die.net/man/3/clock_gettime
 120 /// [mach_absolute_time]: https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/services/services.html
 121 ///
 122 /// **Disclaimer:** These system calls might change over time.
 123 ///
 124 /// > Note: mathematical operations like [`add`] may panic if the underlying
 125 /// > structure cannot represent the new point in time.
 126 ///
 127 /// [`add`]: Instant::add
 128 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 129 #[stable(feature = "time2", since = "1.8.0")]
 130 pub struct Instant(time::Instant);
 131
 132 /// A measurement of the system clock, useful for talking to
 133 /// external entities like the file system or other processes.
 134 ///
 135 /// Distinct from the [`Instant`] type, this time measurement **is not
 136 /// monotonic**. This means that you can save a file to the file system, then
 137 /// save another file to the file system, **and the second file has a
 138 /// `SystemTime` measurement earlier than the first**. In other words, an
 139 /// operation that happens after another operation in real time may have an
 140 /// earlier `SystemTime`!
 141 ///
 142 /// Consequently, comparing two `SystemTime` instances to learn about the
 143 /// duration between them returns a [`Result`] instead of an infallible [`Duration`]
 144 /// to indicate that this sort of time drift may happen and needs to be handled.
 145 ///
 146 /// Although a `SystemTime` cannot be directly inspected, the [`UNIX_EPOCH`]
 147 /// constant is provided in this module as an anchor in time to learn
 148 /// information about a `SystemTime`. By calculating the duration from this
 149 /// fixed point in time, a `SystemTime` can be converted to a human-readable time,
 150 /// or perhaps some other string representation.
 151 ///
 152 /// The size of a `SystemTime` struct may vary depending on the target operating
 153 /// system.
 154 ///
 155 /// Example:
 156 ///
 157 /// ```no_run
 158 /// use std::time::{Duration, SystemTime};
 159 /// use std::thread::sleep;
 160 ///
 161 /// fn main() {
 162 ///    let now = SystemTime::now();
 163 ///
 164 ///    // we sleep for 2 seconds
 165 ///    sleep(Duration::new(2, 0));
 166 ///    match now.elapsed() {
 167 ///        Ok(elapsed) => {
 168 ///            // it prints '2'
 169 ///            println!("{}", elapsed.as_secs());
 170 ///        }
 171 ///        Err(e) => {
 172 ///            // an error occurred!
 173 ///            println!("Error: {:?}", e);
 174 ///        }
 175 ///    }
 176 /// }
 177 /// ```
 178 ///
 179 /// # Underlying System calls
 180 /// Currently, the following system calls are being used to get the current time using `now()`:
 181 ///
 182 /// |  Platform |               System call                                            |
 183 /// |-----------|----------------------------------------------------------------------|
 184 /// | SGX       | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
 185 /// | UNIX      | [clock_gettime (Realtime Clock)]                                     |
 186 /// | Darwin    | [gettimeofday]                                                       |
 187 /// | VXWorks   | [clock_gettime (Realtime Clock)]                                     |
 188 /// | SOLID     | `SOLID_RTC_ReadTime`                                                 |
 189 /// | WASI      | [__wasi_clock_time_get (Realtime Clock)]                             |
 190 /// | Windows   | [GetSystemTimePreciseAsFileTime] / [GetSystemTimeAsFileTime]         |
 191 ///
 192 /// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time
 193 /// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode
 194 /// [gettimeofday]: https://man7.org/linux/man-pages/man2/gettimeofday.2.html
 195 /// [clock_gettime (Realtime Clock)]: https://linux.die.net/man/3/clock_gettime
 196 /// [__wasi_clock_time_get (Realtime Clock)]: https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#clock_time_get
 197 /// [GetSystemTimePreciseAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime
 198 /// [GetSystemTimeAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime
 199 ///
 200 /// **Disclaimer:** These system calls might change over time.
 201 ///
 202 /// > Note: mathematical operations like [`add`] may panic if the underlying
 203 /// > structure cannot represent the new point in time.
 204 ///
 205 /// [`add`]: SystemTime::add
 206 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 207 #[stable(feature = "time2", since = "1.8.0")]
 208 pub struct SystemTime(time::SystemTime);
 209
 210 /// An error returned from the `duration_since` and `elapsed` methods on
 211 /// `SystemTime`, used to learn how far in the opposite direction a system time
 212 /// lies.
 213 ///
 214 /// # Examples
 215 ///
 216 /// ```no_run
 217 /// use std::thread::sleep;
 218 /// use std::time::{Duration, SystemTime};
 219 ///
 220 /// let sys_time = SystemTime::now();
 221 /// sleep(Duration::from_secs(1));
 222 /// let new_sys_time = SystemTime::now();
 223 /// match sys_time.duration_since(new_sys_time) {
 224 ///     Ok(_) => {}
 225 ///     Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
 226 /// }
 227 /// ```
 228 #[derive(Clone, Debug)]
 229 #[stable(feature = "time2", since = "1.8.0")]
 230 pub struct SystemTimeError(Duration);
 231
 232 impl Instant {
 233     /// Returns an instant corresponding to "now".
 234     ///
 235     /// # Examples
 236     ///
 237     /// ```
 238     /// use std::time::Instant;
 239     ///
 240     /// let now = Instant::now();
 241     /// ```
 242     #[must_use]
 243     #[stable(feature = "time2", since = "1.8.0")]
 244     pub fn now() -> Instant {
 245         let os_now = time::Instant::now();
 246
 247         // And here we come upon a sad state of affairs. The whole point of
 248         // `Instant` is that it's monotonically increasing. We've found in the
 249         // wild, however, that it's not actually monotonically increasing for
 250         // one reason or another. These appear to be OS and hardware level bugs,
 251         // and there's not really a whole lot we can do about them. Here's a
 252         // taste of what we've found:
 253         //
 254         // * #48514 - OpenBSD, x86_64
 255         // * #49281 - linux arm64 and s390x
 256         // * #51648 - windows, x86
 257         // * #56560 - windows, x86_64, AWS
 258         // * #56612 - windows, x86, vm (?)
 259         // * #56940 - linux, arm64
 260         // * https://bugzilla.mozilla.org/show_bug.cgi?id=1487778 - a similar
 261         //   Firefox bug
 262         //
 263         // It seems that this just happens a lot in the wild.
 264         // We're seeing panics across various platforms where consecutive calls
 265         // to `Instant::now`, such as via the `elapsed` function, are panicking
 266         // as they're going backwards. Placed here is a last-ditch effort to try
 267         // to fix things up. We keep a global "latest now" instance which is
 268         // returned instead of what the OS says if the OS goes backwards.
 269         //
 270         // To hopefully mitigate the impact of this, a few platforms are
 271         // excluded as "these at least haven't gone backwards yet".
 272         //
 273         // While issues have been seen on arm64 platforms the Arm architecture
 274         // requires that the counter monotonically increases and that it must
 275         // provide a uniform view of system time (e.g. it must not be possible
 276         // for a core to receive a message from another core with a time stamp
 277         // and observe time going backwards (ARM DDI 0487G.b D11.1.2). While
 278         // there have been a few 64bit SoCs that have bugs which cause time to
 279         // not monoticially increase, these have been fixed in the Linux kernel
 280         // and we shouldn't penalize all Arm SoCs for those who refuse to
 281         // update their kernels:
 282         // SUN50I_ERRATUM_UNKNOWN1 - Allwinner A64 / Pine A64 - fixed in 5.1
 283         // FSL_ERRATUM_A008585 - Freescale LS2080A/LS1043A - fixed in 4.10
 284         // HISILICON_ERRATUM_161010101 - Hisilicon 1610 - fixed in 4.11
 285         // ARM64_ERRATUM_858921 - Cortex A73 - fixed in 4.12
 286         if time::Instant::actually_monotonic() {
 287             return Instant(os_now);
 288         }
 289
 290         Instant(monotonic::monotonize(os_now))
 291     }
 292
 293     /// Returns the amount of time elapsed from another instant to this one.
 294     ///
 295     /// # Panics
 296     ///
 297     /// This function will panic if `earlier` is later than `self`.
 298     ///
 299     /// # Examples
 300     ///
 301     /// ```no_run
 302     /// use std::time::{Duration, Instant};
 303     /// use std::thread::sleep;
 304     ///
 305     /// let now = Instant::now();
 306     /// sleep(Duration::new(1, 0));
 307     /// let new_now = Instant::now();
 308     /// println!("{:?}", new_now.duration_since(now));
 309     /// ```
 310     #[must_use]
 311     #[stable(feature = "time2", since = "1.8.0")]
 312     pub fn duration_since(&self, earlier: Instant) -> Duration {
 313         self.0.checked_sub_instant(&earlier.0).expect("supplied instant is later than self")
 314     }
 315
 316     /// Returns the amount of time elapsed from another instant to this one,
 317     /// or None if that instant is later than this one.
 318     ///
 319     /// # Examples
 320     ///
 321     /// ```no_run
 322     /// use std::time::{Duration, Instant};
 323     /// use std::thread::sleep;
 324     ///
 325     /// let now = Instant::now();
 326     /// sleep(Duration::new(1, 0));
 327     /// let new_now = Instant::now();
 328     /// println!("{:?}", new_now.checked_duration_since(now));
 329     /// println!("{:?}", now.checked_duration_since(new_now)); // None
 330     /// ```
 331     #[must_use]
 332     #[stable(feature = "checked_duration_since", since = "1.39.0")]
 333     pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> {
 334         self.0.checked_sub_instant(&earlier.0)
 335     }
 336
 337     /// Returns the amount of time elapsed from another instant to this one,
 338     /// or zero duration if that instant is later than this one.
 339     ///
 340     /// # Examples
 341     ///
 342     /// ```no_run
 343     /// use std::time::{Duration, Instant};
 344     /// use std::thread::sleep;
 345     ///
 346     /// let now = Instant::now();
 347     /// sleep(Duration::new(1, 0));
 348     /// let new_now = Instant::now();
 349     /// println!("{:?}", new_now.saturating_duration_since(now));
 350     /// println!("{:?}", now.saturating_duration_since(new_now)); // 0ns
 351     /// ```
 352     #[must_use]
 353     #[stable(feature = "checked_duration_since", since = "1.39.0")]
 354     pub fn saturating_duration_since(&self, earlier: Instant) -> Duration {
 355         self.checked_duration_since(earlier).unwrap_or_default()
 356     }
 357
 358     /// Returns the amount of time elapsed since this instant was created.
 359     ///
 360     /// # Panics
 361     ///
 362     /// This function may panic if the current time is earlier than this
 363     /// instant, which is something that can happen if an `Instant` is
 364     /// produced synthetically.
 365     ///
 366     /// # Examples
 367     ///
 368     /// ```no_run
 369     /// use std::thread::sleep;
 370     /// use std::time::{Duration, Instant};
 371     ///
 372     /// let instant = Instant::now();
 373     /// let three_secs = Duration::from_secs(3);
 374     /// sleep(three_secs);
 375     /// assert!(instant.elapsed() >= three_secs);
 376     /// ```
 377     #[must_use]
 378     #[stable(feature = "time2", since = "1.8.0")]
 379     pub fn elapsed(&self) -> Duration {
 380         Instant::now() - *self
 381     }
 382
 383     /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
 384     /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
 385     /// otherwise.
 386     #[stable(feature = "time_checked_add", since = "1.34.0")]
 387     pub fn checked_add(&self, duration: Duration) -> Option<Instant> {
 388         self.0.checked_add_duration(&duration).map(Instant)
 389     }
 390
 391     /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
 392     /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
 393     /// otherwise.
 394     #[stable(feature = "time_checked_add", since = "1.34.0")]
 395     pub fn checked_sub(&self, duration: Duration) -> Option<Instant> {
 396         self.0.checked_sub_duration(&duration).map(Instant)
 397     }
 398 }
 399
 400 #[stable(feature = "time2", since = "1.8.0")]
 401 impl Add<Duration> for Instant {
 402     type Output = Instant;
 403
 404     /// # Panics
 405     ///
 406     /// This function may panic if the resulting point in time cannot be represented by the
 407     /// underlying data structure. See [`Instant::checked_add`] for a version without panic.
 408     fn add(self, other: Duration) -> Instant {
 409         self.checked_add(other).expect("overflow when adding duration to instant")
 410     }
 411 }
 412
 413 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 414 impl AddAssign<Duration> for Instant {
 415     fn add_assign(&mut self, other: Duration) {
 416         *self = *self + other;
 417     }
 418 }
 419
 420 #[stable(feature = "time2", since = "1.8.0")]
 421 impl Sub<Duration> for Instant {
 422     type Output = Instant;
 423
 424     fn sub(self, other: Duration) -> Instant {
 425         self.checked_sub(other).expect("overflow when subtracting duration from instant")
 426     }
 427 }
 428
 429 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 430 impl SubAssign<Duration> for Instant {
 431     fn sub_assign(&mut self, other: Duration) {
 432         *self = *self - other;
 433     }
 434 }
 435
 436 #[stable(feature = "time2", since = "1.8.0")]
 437 impl Sub<Instant> for Instant {
 438     type Output = Duration;
 439
 440     fn sub(self, other: Instant) -> Duration {
 441         self.duration_since(other)
 442     }
 443 }
 444
 445 #[stable(feature = "time2", since = "1.8.0")]
 446 impl fmt::Debug for Instant {
 447     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 448         self.0.fmt(f)
 449     }
 450 }
 451
 452 impl SystemTime {
 453     /// An anchor in time which can be used to create new `SystemTime` instances or
 454     /// learn about where in time a `SystemTime` lies.
 455     ///
 456     /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
 457     /// respect to the system clock. Using `duration_since` on an existing
 458     /// `SystemTime` instance can tell how far away from this point in time a
 459     /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
 460     /// `SystemTime` instance to represent another fixed point in time.
 461     ///
 462     /// # Examples
 463     ///
 464     /// ```no_run
 465     /// use std::time::SystemTime;
 466     ///
 467     /// match SystemTime::now().duration_since(SystemTime::UNIX_EPOCH) {
 468     ///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
 469     ///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
 470     /// }
 471     /// ```
 472     #[stable(feature = "assoc_unix_epoch", since = "1.28.0")]
 473     pub const UNIX_EPOCH: SystemTime = UNIX_EPOCH;
 474
 475     /// Returns the system time corresponding to "now".
 476     ///
 477     /// # Examples
 478     ///
 479     /// ```
 480     /// use std::time::SystemTime;
 481     ///
 482     /// let sys_time = SystemTime::now();
 483     /// ```
 484     #[must_use]
 485     #[stable(feature = "time2", since = "1.8.0")]
 486     pub fn now() -> SystemTime {
 487         SystemTime(time::SystemTime::now())
 488     }
 489
 490     /// Returns the amount of time elapsed from an earlier point in time.
 491     ///
 492     /// This function may fail because measurements taken earlier are not
 493     /// guaranteed to always be before later measurements (due to anomalies such
 494     /// as the system clock being adjusted either forwards or backwards).
 495     /// [`Instant`] can be used to measure elapsed time without this risk of failure.
 496     ///
 497     /// If successful, <code>[Ok]\([Duration])</code> is returned where the duration represents
 498     /// the amount of time elapsed from the specified measurement to this one.
 499     ///
 500     /// Returns an [`Err`] if `earlier` is later than `self`, and the error
 501     /// contains how far from `self` the time is.
 502     ///
 503     /// # Examples
 504     ///
 505     /// ```no_run
 506     /// use std::time::SystemTime;
 507     ///
 508     /// let sys_time = SystemTime::now();
 509     /// let new_sys_time = SystemTime::now();
 510     /// let difference = new_sys_time.duration_since(sys_time)
 511     ///     .expect("Clock may have gone backwards");
 512     /// println!("{:?}", difference);
 513     /// ```
 514     #[stable(feature = "time2", since = "1.8.0")]
 515     pub fn duration_since(&self, earlier: SystemTime) -> Result<Duration, SystemTimeError> {
 516         self.0.sub_time(&earlier.0).map_err(SystemTimeError)
 517     }
 518
 519     /// Returns the difference between the clock time when this
 520     /// system time was created, and the current clock time.
 521     ///
 522     /// This function may fail as the underlying system clock is susceptible to
 523     /// drift and updates (e.g., the system clock could go backwards), so this
 524     /// function might not always succeed. If successful, <code>[Ok]\([Duration])</code> is
 525     /// returned where the duration represents the amount of time elapsed from
 526     /// this time measurement to the current time.
 527     ///
 528     /// To measure elapsed time reliably, use [`Instant`] instead.
 529     ///
 530     /// Returns an [`Err`] if `self` is later than the current system time, and
 531     /// the error contains how far from the current system time `self` is.
 532     ///
 533     /// # Examples
 534     ///
 535     /// ```no_run
 536     /// use std::thread::sleep;
 537     /// use std::time::{Duration, SystemTime};
 538     ///
 539     /// let sys_time = SystemTime::now();
 540     /// let one_sec = Duration::from_secs(1);
 541     /// sleep(one_sec);
 542     /// assert!(sys_time.elapsed().unwrap() >= one_sec);
 543     /// ```
 544     #[stable(feature = "time2", since = "1.8.0")]
 545     pub fn elapsed(&self) -> Result<Duration, SystemTimeError> {
 546         SystemTime::now().duration_since(*self)
 547     }
 548
 549     /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
 550     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
 551     /// otherwise.
 552     #[stable(feature = "time_checked_add", since = "1.34.0")]
 553     pub fn checked_add(&self, duration: Duration) -> Option<SystemTime> {
 554         self.0.checked_add_duration(&duration).map(SystemTime)
 555     }
 556
 557     /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
 558     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
 559     /// otherwise.
 560     #[stable(feature = "time_checked_add", since = "1.34.0")]
 561     pub fn checked_sub(&self, duration: Duration) -> Option<SystemTime> {
 562         self.0.checked_sub_duration(&duration).map(SystemTime)
 563     }
 564 }
 565
 566 #[stable(feature = "time2", since = "1.8.0")]
 567 impl Add<Duration> for SystemTime {
 568     type Output = SystemTime;
 569
 570     /// # Panics
 571     ///
 572     /// This function may panic if the resulting point in time cannot be represented by the
 573     /// underlying data structure. See [`SystemTime::checked_add`] for a version without panic.
 574     fn add(self, dur: Duration) -> SystemTime {
 575         self.checked_add(dur).expect("overflow when adding duration to instant")
 576     }
 577 }
 578
 579 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 580 impl AddAssign<Duration> for SystemTime {
 581     fn add_assign(&mut self, other: Duration) {
 582         *self = *self + other;
 583     }
 584 }
 585
 586 #[stable(feature = "time2", since = "1.8.0")]
 587 impl Sub<Duration> for SystemTime {
 588     type Output = SystemTime;
 589
 590     fn sub(self, dur: Duration) -> SystemTime {
 591         self.checked_sub(dur).expect("overflow when subtracting duration from instant")
 592     }
 593 }
 594
 595 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 596 impl SubAssign<Duration> for SystemTime {
 597     fn sub_assign(&mut self, other: Duration) {
 598         *self = *self - other;
 599     }
 600 }
 601
 602 #[stable(feature = "time2", since = "1.8.0")]
 603 impl fmt::Debug for SystemTime {
 604     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 605         self.0.fmt(f)
 606     }
 607 }
 608
 609 /// An anchor in time which can be used to create new `SystemTime` instances or
 610 /// learn about where in time a `SystemTime` lies.
 611 ///
 612 /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
 613 /// respect to the system clock. Using `duration_since` on an existing
 614 /// [`SystemTime`] instance can tell how far away from this point in time a
 615 /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
 616 /// [`SystemTime`] instance to represent another fixed point in time.
 617 ///
 618 /// # Examples
 619 ///
 620 /// ```no_run
 621 /// use std::time::{SystemTime, UNIX_EPOCH};
 622 ///
 623 /// match SystemTime::now().duration_since(UNIX_EPOCH) {
 624 ///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
 625 ///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
 626 /// }
 627 /// ```
 628 #[stable(feature = "time2", since = "1.8.0")]
 629 pub const UNIX_EPOCH: SystemTime = SystemTime(time::UNIX_EPOCH);
 630
 631 impl SystemTimeError {
 632     /// Returns the positive duration which represents how far forward the
 633     /// second system time was from the first.
 634     ///
 635     /// A `SystemTimeError` is returned from the [`SystemTime::duration_since`]
 636     /// and [`SystemTime::elapsed`] methods whenever the second system time
 637     /// represents a point later in time than the `self` of the method call.
 638     ///
 639     /// # Examples
 640     ///
 641     /// ```no_run
 642     /// use std::thread::sleep;
 643     /// use std::time::{Duration, SystemTime};
 644     ///
 645     /// let sys_time = SystemTime::now();
 646     /// sleep(Duration::from_secs(1));
 647     /// let new_sys_time = SystemTime::now();
 648     /// match sys_time.duration_since(new_sys_time) {
 649     ///     Ok(_) => {}
 650     ///     Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
 651     /// }
 652     /// ```
 653     #[must_use]
 654     #[stable(feature = "time2", since = "1.8.0")]
 655     pub fn duration(&self) -> Duration {
 656         self.0
 657     }
 658 }
 659
 660 #[stable(feature = "time2", since = "1.8.0")]
 661 impl Error for SystemTimeError {
 662     #[allow(deprecated)]
 663     fn description(&self) -> &str {
 664         "other time was not earlier than self"
 665     }
 666 }
 667
 668 #[stable(feature = "time2", since = "1.8.0")]
 669 impl fmt::Display for SystemTimeError {
 670     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 671         write!(f, "second time provided was later than self")
 672     }
 673 }
 674
 675 impl FromInner<time::SystemTime> for SystemTime {
 676     fn from_inner(time: time::SystemTime) -> SystemTime {
 677         SystemTime(time)
 678     }
 679 }