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::FromSecsError;
  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     #[stable(feature = "time2", since = "1.8.0")]
 243     pub fn now() -> Instant {
 244         let os_now = time::Instant::now();
 245
 246         // And here we come upon a sad state of affairs. The whole point of
 247         // `Instant` is that it's monotonically increasing. We've found in the
 248         // wild, however, that it's not actually monotonically increasing for
 249         // one reason or another. These appear to be OS and hardware level bugs,
 250         // and there's not really a whole lot we can do about them. Here's a
 251         // taste of what we've found:
 252         //
 253         // * #48514 - OpenBSD, x86_64
 254         // * #49281 - linux arm64 and s390x
 255         // * #51648 - windows, x86
 256         // * #56560 - windows, x86_64, AWS
 257         // * #56612 - windows, x86, vm (?)
 258         // * #56940 - linux, arm64
 259         // * https://bugzilla.mozilla.org/show_bug.cgi?id=1487778 - a similar
 260         //   Firefox bug
 261         //
 262         // It seems that this just happens a lot in the wild.
 263         // We're seeing panics across various platforms where consecutive calls
 264         // to `Instant::now`, such as via the `elapsed` function, are panicking
 265         // as they're going backwards. Placed here is a last-ditch effort to try
 266         // to fix things up. We keep a global "latest now" instance which is
 267         // returned instead of what the OS says if the OS goes backwards.
 268         //
 269         // To hopefully mitigate the impact of this, a few platforms are
 270         // excluded as "these at least haven't gone backwards yet".
 271         if time::Instant::actually_monotonic() {
 272             return Instant(os_now);
 273         }
 274
 275         Instant(monotonic::monotonize(os_now))
 276     }
 277
 278     /// Returns the amount of time elapsed from another instant to this one.
 279     ///
 280     /// # Panics
 281     ///
 282     /// This function will panic if `earlier` is later than `self`.
 283     ///
 284     /// # Examples
 285     ///
 286     /// ```no_run
 287     /// use std::time::{Duration, Instant};
 288     /// use std::thread::sleep;
 289     ///
 290     /// let now = Instant::now();
 291     /// sleep(Duration::new(1, 0));
 292     /// let new_now = Instant::now();
 293     /// println!("{:?}", new_now.duration_since(now));
 294     /// ```
 295     #[stable(feature = "time2", since = "1.8.0")]
 296     pub fn duration_since(&self, earlier: Instant) -> Duration {
 297         self.0.checked_sub_instant(&earlier.0).expect("supplied instant is later than self")
 298     }
 299
 300     /// Returns the amount of time elapsed from another instant to this one,
 301     /// or None if that instant is later than this one.
 302     ///
 303     /// # Examples
 304     ///
 305     /// ```no_run
 306     /// use std::time::{Duration, Instant};
 307     /// use std::thread::sleep;
 308     ///
 309     /// let now = Instant::now();
 310     /// sleep(Duration::new(1, 0));
 311     /// let new_now = Instant::now();
 312     /// println!("{:?}", new_now.checked_duration_since(now));
 313     /// println!("{:?}", now.checked_duration_since(new_now)); // None
 314     /// ```
 315     #[stable(feature = "checked_duration_since", since = "1.39.0")]
 316     pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> {
 317         self.0.checked_sub_instant(&earlier.0)
 318     }
 319
 320     /// Returns the amount of time elapsed from another instant to this one,
 321     /// or zero duration if that instant is later than this one.
 322     ///
 323     /// # Examples
 324     ///
 325     /// ```no_run
 326     /// use std::time::{Duration, Instant};
 327     /// use std::thread::sleep;
 328     ///
 329     /// let now = Instant::now();
 330     /// sleep(Duration::new(1, 0));
 331     /// let new_now = Instant::now();
 332     /// println!("{:?}", new_now.saturating_duration_since(now));
 333     /// println!("{:?}", now.saturating_duration_since(new_now)); // 0ns
 334     /// ```
 335     #[stable(feature = "checked_duration_since", since = "1.39.0")]
 336     pub fn saturating_duration_since(&self, earlier: Instant) -> Duration {
 337         self.checked_duration_since(earlier).unwrap_or_default()
 338     }
 339
 340     /// Returns the amount of time elapsed since this instant was created.
 341     ///
 342     /// # Panics
 343     ///
 344     /// This function may panic if the current time is earlier than this
 345     /// instant, which is something that can happen if an `Instant` is
 346     /// produced synthetically.
 347     ///
 348     /// # Examples
 349     ///
 350     /// ```no_run
 351     /// use std::thread::sleep;
 352     /// use std::time::{Duration, Instant};
 353     ///
 354     /// let instant = Instant::now();
 355     /// let three_secs = Duration::from_secs(3);
 356     /// sleep(three_secs);
 357     /// assert!(instant.elapsed() >= three_secs);
 358     /// ```
 359     #[stable(feature = "time2", since = "1.8.0")]
 360     pub fn elapsed(&self) -> Duration {
 361         Instant::now() - *self
 362     }
 363
 364     /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
 365     /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
 366     /// otherwise.
 367     #[stable(feature = "time_checked_add", since = "1.34.0")]
 368     pub fn checked_add(&self, duration: Duration) -> Option<Instant> {
 369         self.0.checked_add_duration(&duration).map(Instant)
 370     }
 371
 372     /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
 373     /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
 374     /// otherwise.
 375     #[stable(feature = "time_checked_add", since = "1.34.0")]
 376     pub fn checked_sub(&self, duration: Duration) -> Option<Instant> {
 377         self.0.checked_sub_duration(&duration).map(Instant)
 378     }
 379 }
 380
 381 #[stable(feature = "time2", since = "1.8.0")]
 382 impl Add<Duration> for Instant {
 383     type Output = Instant;
 384
 385     /// # Panics
 386     ///
 387     /// This function may panic if the resulting point in time cannot be represented by the
 388     /// underlying data structure. See [`Instant::checked_add`] for a version without panic.
 389     fn add(self, other: Duration) -> Instant {
 390         self.checked_add(other).expect("overflow when adding duration to instant")
 391     }
 392 }
 393
 394 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 395 impl AddAssign<Duration> for Instant {
 396     fn add_assign(&mut self, other: Duration) {
 397         *self = *self + other;
 398     }
 399 }
 400
 401 #[stable(feature = "time2", since = "1.8.0")]
 402 impl Sub<Duration> for Instant {
 403     type Output = Instant;
 404
 405     fn sub(self, other: Duration) -> Instant {
 406         self.checked_sub(other).expect("overflow when subtracting duration from instant")
 407     }
 408 }
 409
 410 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 411 impl SubAssign<Duration> for Instant {
 412     fn sub_assign(&mut self, other: Duration) {
 413         *self = *self - other;
 414     }
 415 }
 416
 417 #[stable(feature = "time2", since = "1.8.0")]
 418 impl Sub<Instant> for Instant {
 419     type Output = Duration;
 420
 421     fn sub(self, other: Instant) -> Duration {
 422         self.duration_since(other)
 423     }
 424 }
 425
 426 #[stable(feature = "time2", since = "1.8.0")]
 427 impl fmt::Debug for Instant {
 428     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 429         self.0.fmt(f)
 430     }
 431 }
 432
 433 impl SystemTime {
 434     /// An anchor in time which can be used to create new `SystemTime` instances or
 435     /// learn about where in time a `SystemTime` lies.
 436     ///
 437     /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
 438     /// respect to the system clock. Using `duration_since` on an existing
 439     /// `SystemTime` instance can tell how far away from this point in time a
 440     /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
 441     /// `SystemTime` instance to represent another fixed point in time.
 442     ///
 443     /// # Examples
 444     ///
 445     /// ```no_run
 446     /// use std::time::SystemTime;
 447     ///
 448     /// match SystemTime::now().duration_since(SystemTime::UNIX_EPOCH) {
 449     ///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
 450     ///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
 451     /// }
 452     /// ```
 453     #[stable(feature = "assoc_unix_epoch", since = "1.28.0")]
 454     pub const UNIX_EPOCH: SystemTime = UNIX_EPOCH;
 455
 456     /// Returns the system time corresponding to "now".
 457     ///
 458     /// # Examples
 459     ///
 460     /// ```
 461     /// use std::time::SystemTime;
 462     ///
 463     /// let sys_time = SystemTime::now();
 464     /// ```
 465     #[stable(feature = "time2", since = "1.8.0")]
 466     pub fn now() -> SystemTime {
 467         SystemTime(time::SystemTime::now())
 468     }
 469
 470     /// Returns the amount of time elapsed from an earlier point in time.
 471     ///
 472     /// This function may fail because measurements taken earlier are not
 473     /// guaranteed to always be before later measurements (due to anomalies such
 474     /// as the system clock being adjusted either forwards or backwards).
 475     /// [`Instant`] can be used to measure elapsed time without this risk of failure.
 476     ///
 477     /// If successful, <code>[Ok]\([Duration])</code> is returned where the duration represents
 478     /// the amount of time elapsed from the specified measurement to this one.
 479     ///
 480     /// Returns an [`Err`] if `earlier` is later than `self`, and the error
 481     /// contains how far from `self` the time is.
 482     ///
 483     /// # Examples
 484     ///
 485     /// ```no_run
 486     /// use std::time::SystemTime;
 487     ///
 488     /// let sys_time = SystemTime::now();
 489     /// let new_sys_time = SystemTime::now();
 490     /// let difference = new_sys_time.duration_since(sys_time)
 491     ///     .expect("Clock may have gone backwards");
 492     /// println!("{:?}", difference);
 493     /// ```
 494     #[stable(feature = "time2", since = "1.8.0")]
 495     pub fn duration_since(&self, earlier: SystemTime) -> Result<Duration, SystemTimeError> {
 496         self.0.sub_time(&earlier.0).map_err(SystemTimeError)
 497     }
 498
 499     /// Returns the difference between the clock time when this
 500     /// system time was created, and the current clock time.
 501     ///
 502     /// This function may fail as the underlying system clock is susceptible to
 503     /// drift and updates (e.g., the system clock could go backwards), so this
 504     /// function might not always succeed. If successful, <code>[Ok]\([Duration])</code> is
 505     /// returned where the duration represents the amount of time elapsed from
 506     /// this time measurement to the current time.
 507     ///
 508     /// To measure elapsed time reliably, use [`Instant`] instead.
 509     ///
 510     /// Returns an [`Err`] if `self` is later than the current system time, and
 511     /// the error contains how far from the current system time `self` is.
 512     ///
 513     /// # Examples
 514     ///
 515     /// ```no_run
 516     /// use std::thread::sleep;
 517     /// use std::time::{Duration, SystemTime};
 518     ///
 519     /// let sys_time = SystemTime::now();
 520     /// let one_sec = Duration::from_secs(1);
 521     /// sleep(one_sec);
 522     /// assert!(sys_time.elapsed().unwrap() >= one_sec);
 523     /// ```
 524     #[stable(feature = "time2", since = "1.8.0")]
 525     pub fn elapsed(&self) -> Result<Duration, SystemTimeError> {
 526         SystemTime::now().duration_since(*self)
 527     }
 528
 529     /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
 530     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
 531     /// otherwise.
 532     #[stable(feature = "time_checked_add", since = "1.34.0")]
 533     pub fn checked_add(&self, duration: Duration) -> Option<SystemTime> {
 534         self.0.checked_add_duration(&duration).map(SystemTime)
 535     }
 536
 537     /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
 538     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
 539     /// otherwise.
 540     #[stable(feature = "time_checked_add", since = "1.34.0")]
 541     pub fn checked_sub(&self, duration: Duration) -> Option<SystemTime> {
 542         self.0.checked_sub_duration(&duration).map(SystemTime)
 543     }
 544 }
 545
 546 #[stable(feature = "time2", since = "1.8.0")]
 547 impl Add<Duration> for SystemTime {
 548     type Output = SystemTime;
 549
 550     /// # Panics
 551     ///
 552     /// This function may panic if the resulting point in time cannot be represented by the
 553     /// underlying data structure. See [`SystemTime::checked_add`] for a version without panic.
 554     fn add(self, dur: Duration) -> SystemTime {
 555         self.checked_add(dur).expect("overflow when adding duration to instant")
 556     }
 557 }
 558
 559 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 560 impl AddAssign<Duration> for SystemTime {
 561     fn add_assign(&mut self, other: Duration) {
 562         *self = *self + other;
 563     }
 564 }
 565
 566 #[stable(feature = "time2", since = "1.8.0")]
 567 impl Sub<Duration> for SystemTime {
 568     type Output = SystemTime;
 569
 570     fn sub(self, dur: Duration) -> SystemTime {
 571         self.checked_sub(dur).expect("overflow when subtracting duration from instant")
 572     }
 573 }
 574
 575 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 576 impl SubAssign<Duration> for SystemTime {
 577     fn sub_assign(&mut self, other: Duration) {
 578         *self = *self - other;
 579     }
 580 }
 581
 582 #[stable(feature = "time2", since = "1.8.0")]
 583 impl fmt::Debug for SystemTime {
 584     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 585         self.0.fmt(f)
 586     }
 587 }
 588
 589 /// An anchor in time which can be used to create new `SystemTime` instances or
 590 /// learn about where in time a `SystemTime` lies.
 591 ///
 592 /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
 593 /// respect to the system clock. Using `duration_since` on an existing
 594 /// [`SystemTime`] instance can tell how far away from this point in time a
 595 /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
 596 /// [`SystemTime`] instance to represent another fixed point in time.
 597 ///
 598 /// # Examples
 599 ///
 600 /// ```no_run
 601 /// use std::time::{SystemTime, UNIX_EPOCH};
 602 ///
 603 /// match SystemTime::now().duration_since(UNIX_EPOCH) {
 604 ///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
 605 ///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
 606 /// }
 607 /// ```
 608 #[stable(feature = "time2", since = "1.8.0")]
 609 pub const UNIX_EPOCH: SystemTime = SystemTime(time::UNIX_EPOCH);
 610
 611 impl SystemTimeError {
 612     /// Returns the positive duration which represents how far forward the
 613     /// second system time was from the first.
 614     ///
 615     /// A `SystemTimeError` is returned from the [`SystemTime::duration_since`]
 616     /// and [`SystemTime::elapsed`] methods whenever the second system time
 617     /// represents a point later in time than the `self` of the method call.
 618     ///
 619     /// # Examples
 620     ///
 621     /// ```no_run
 622     /// use std::thread::sleep;
 623     /// use std::time::{Duration, SystemTime};
 624     ///
 625     /// let sys_time = SystemTime::now();
 626     /// sleep(Duration::from_secs(1));
 627     /// let new_sys_time = SystemTime::now();
 628     /// match sys_time.duration_since(new_sys_time) {
 629     ///     Ok(_) => {}
 630     ///     Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
 631     /// }
 632     /// ```
 633     #[stable(feature = "time2", since = "1.8.0")]
 634     pub fn duration(&self) -> Duration {
 635         self.0
 636     }
 637 }
 638
 639 #[stable(feature = "time2", since = "1.8.0")]
 640 impl Error for SystemTimeError {
 641     #[allow(deprecated)]
 642     fn description(&self) -> &str {
 643         "other time was not earlier than self"
 644     }
 645 }
 646
 647 #[stable(feature = "time2", since = "1.8.0")]
 648 impl fmt::Display for SystemTimeError {
 649     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 650         write!(f, "second time provided was later than self")
 651     }
 652 }
 653
 654 impl FromInner<time::SystemTime> for SystemTime {
 655     fn from_inner(time: time::SystemTime) -> SystemTime {
 656         SystemTime(time)
 657     }
 658 }