1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
//! 时间量化。
//!
//! Example:
//!
//! ```
//! use std::time::Duration;
//!
//! let five_seconds = Duration::new(5, 0);
//! // 这两个声明是等效的
//! assert_eq!(Duration::new(5, 0), Duration::from_secs(5));
//! ```

#![stable(feature = "time", since = "1.3.0")]

#[cfg(test)]
mod tests;

use crate::cmp;
use crate::error::Error;
use crate::fmt;
use crate::ops::{Add, AddAssign, Sub, SubAssign};
use crate::sys::time;
use crate::sys_common::mutex::StaticMutex;
use crate::sys_common::FromInner;

#[stable(feature = "time", since = "1.3.0")]
pub use core::time::Duration;

/// 单调非递减时钟的度量。
/// 不透明,仅对 `Duration` 有用。
///
/// 创建时始终保证瞬时不小于任何先前测量的瞬时,并且对于执行诸如测量基准或计时操作花费多长时间等任务通常很有用。
///
///
/// 但是请注意,不能保证瞬间稳定。换句话说,基础时钟的每个刻度可能不一样长 (例如
/// 几秒钟可能比其他更长)。瞬间可能会向前跳跃或经历时间膨胀 (减速或加速),但永远不会向后退。
///
/// 即时消息是不透明的类型,只能相互比较。没有方法可以立即获取 "the number of seconds"。
/// 相反,它仅允许测量两个瞬间之间的持续时间 (或比较两个瞬间)。
///
/// `Instant` 结构体的大小可能会因目标操作系统而异。
///
/// Example:
///
/// ```no_run
/// use std::time::{Duration, Instant};
/// use std::thread::sleep;
///
/// fn main() {
///    let now = Instant::now();
///
///    // 我们睡了 2 秒钟
///    sleep(Duration::new(2, 0));
///    // 它打印 '2'
///    println!("{}", now.elapsed().as_secs());
/// }
/// ```
///
/// # 特定于操作系统的行为
///
/// `Instant` 是系统特定类型的包装,并且其行为可能取决于基础操作系统。
/// 例如,以下代码段在 Linux 上很好,但在 macOS 上为 panics:
///
/// ```no_run
/// use std::time::{Instant, Duration};
///
/// let now = Instant::now();
/// let max_nanoseconds = u64::MAX / 1_000_000_000;
/// let duration = Duration::new(max_nanoseconds, 0);
/// println!("{:?}", now + duration);
/// ```
///
/// # 底层系统调用
/// 当前,正在使用以下系统调用来使用 `now()` 获取当前时间:
///
/// |  Platform |               System call                                            |
/// |-----------|----------------------------------------------------------------------|
/// | SGX       | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
/// | UNIX      | [clock_gettime (Monotonic Clock)]                                    |
/// | Darwin    | [mach_absolute_time]                                                 |
/// | VXWorks   | [clock_gettime (Monotonic Clock)]                                    |
/// | WASI      | [__wasi_clock_time_get (Monotonic Clock)]                            |
/// | Windows   | [QueryPerformanceCounter]                                            |
///
/// [QueryPerformanceCounter]: https://docs.microsoft.com/en-us/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter
/// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time
/// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode
/// [__wasi_clock_time_get (Monotonic Clock)]: https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#clock_time_get
/// [clock_gettime (Monotonic Clock)]: https://linux.die.net/man/3/clock_gettime
/// [mach_absolute_time]: https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/services/services.html
///
/// **免责声明:** 这些系统调用可能会随时间变化。
///
/// > Note: 如果 [`add`] 的数学运算可能是 panic
/// > 结构体不能代表新的时间点。
///
/// [`add`]: Instant::add
///
///
///
///
///
///
///
///
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[stable(feature = "time2", since = "1.8.0")]
pub struct Instant(time::Instant);

/// 系统时钟的度量,对于与文件系统或其他进程之类的外部实体进行通信很有用。
///
/// 与 [`Instant`] 类型不同,这次的测量 **不是单调的**。
/// 这意味着您可以将文件保存到文件系统,然后再将另一个文件保存到文件系统,**并且第二个文件的 `SystemTime` 测量值比第一个文件早**。
/// 换句话说,在另一个实时操作之后实时发生的操作可能具有更早的 `SystemTime`!
///
/// 因此,比较两个 `SystemTime` 实例以了解它们之间的持续时间将返回 [`Result`] 而不是绝对的 [`Duration`],以指示这种时间漂移可能发生并且需要处理。
///
///
/// 尽管无法直接检查 `SystemTime`,但此模块中提供了 [`UNIX_EPOCH`] 常量作为及时了解有关 `SystemTime` 信息的锚点。
/// 通过从该固定时间点计算持续时间,可以将 `SystemTime` 转换为人类可读的时间,或者转换为其他字符串表示形式。
///
/// `SystemTime` 结构体的大小可能会因目标操作系统而异。
///
/// Example:
///
/// ```no_run
/// use std::time::{Duration, SystemTime};
/// use std::thread::sleep;
///
/// fn main() {
///    let now = SystemTime::now();
///
///    // 我们睡了 2 秒钟
///    sleep(Duration::new(2, 0));
///    match now.elapsed() {
///        Ok(elapsed) => {
///            // 它打印 '2'
///            println!("{}", elapsed.as_secs());
///        }
///        Err(e) => {
///            // 发生错误!
///            println!("Error: {:?}", e);
///        }
///    }
/// }
/// ```
///
/// # 底层系统调用
/// 当前,正在使用以下系统调用来使用 `now()` 获取当前时间:
///
/// |  Platform |               System call                                            |
/// |-----------|----------------------------------------------------------------------|
/// | SGX       | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
/// | UNIX      | [clock_gettime (Realtime Clock)]                                     |
/// | Darwin    | [gettimeofday]                                                       |
/// | VXWorks   | [clock_gettime (Realtime Clock)]                                     |
/// | WASI      | [__wasi_clock_time_get (Realtime Clock)]                             |
/// | Windows   | [GetSystemTimePreciseAsFileTime] / [GetSystemTimeAsFileTime]         |
///
/// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time
/// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode
/// [gettimeofday]: https://man7.org/linux/man-pages/man2/gettimeofday.2.html
/// [clock_gettime (Realtime Clock)]: https://linux.die.net/man/3/clock_gettime
/// [__wasi_clock_time_get (Realtime Clock)]: https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#clock_time_get
/// [GetSystemTimePreciseAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime
/// [GetSystemTimeAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime
///
/// **免责声明:** 这些系统调用可能会随时间变化。
///
/// > Note: 如果 [`add`] 的数学运算可能是 panic
/// > 结构体不能代表新的时间点。
///
/// [`add`]: SystemTime::add
///
///
///
///
///
///
///
///
///
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[stable(feature = "time2", since = "1.8.0")]
pub struct SystemTime(time::SystemTime);

/// `SystemTime` 的 `duration_since` 和 `elapsed` 方法返回的错误,用于了解系统时间在相反方向上的距离。
///
///
/// # Examples
///
/// ```no_run
/// use std::thread::sleep;
/// use std::time::{Duration, SystemTime};
///
/// let sys_time = SystemTime::now();
/// sleep(Duration::from_secs(1));
/// let new_sys_time = SystemTime::now();
/// match sys_time.duration_since(new_sys_time) {
///     Ok(_) => {}
///     Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
/// }
/// ```
///
#[derive(Clone, Debug)]
#[stable(feature = "time2", since = "1.8.0")]
pub struct SystemTimeError(Duration);

impl Instant {
    /// 返回对应于 "now" 的瞬间。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::time::Instant;
    ///
    /// let now = Instant::now();
    /// ```
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn now() -> Instant {
        let os_now = time::Instant::now();

        // 在这里,我们遇到了一种悲惨的状况。`Instant` 的全部要点是它是单调递增的。但是,我们发现在野外它实际上并不是由于一个或另一个原因而单调增加。
        //
        // 这些似乎是操作系统和硬件级别的错误,我们实际上并不能做很多事情。以下是我们发现的内容:
        //
        // * #48514 - OpenBSD, x86_64
        // * #49281 - linux arm64 和 s390x
        // * #51648 - windows, x86
        // * #56560 - windows, x86_64, AWS
        // * #56612 - windows,x86,VM (?)
        // * #56940 - linux, arm64
        // * https://bugzilla.mozilla.org/show_bug.cgi?id=1487778-asimilarFirefoxbug
        //
        // 似乎这在野外经常发生。
        // 我们正在各种平台上看到 panics,在这些平台上,通过 `elapsed` 函数对 `Instant::now` 的连续调用在向后倒退时会感到恐慌。
        // 此处放置的是最后一滴尝试以解决问题的方法。
        // 我们保留一个 "latest now" 实例,如果 OS 向后运行,则返回该实例,而不是 OS 所说的。
        //
        // 为了希望减轻这种影响,"these at least haven't gone backwards yet" 排除了一些平台。
        //
        //
        //
        //
        //
        //
        //
        if time::Instant::actually_monotonic() {
            return Instant(os_now);
        }

        static LOCK: StaticMutex = StaticMutex::new();
        static mut LAST_NOW: time::Instant = time::Instant::zero();
        unsafe {
            let _lock = LOCK.lock();
            let now = cmp::max(LAST_NOW, os_now);
            LAST_NOW = now;
            Instant(now)
        }
    }

    /// 返回从另一个时刻到该时刻所经过的时间。
    ///
    /// # Panics
    ///
    /// 如果 `earlier` 晚于 `self`,则此函数将为 panic。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::time::{Duration, Instant};
    /// use std::thread::sleep;
    ///
    /// let now = Instant::now();
    /// sleep(Duration::new(1, 0));
    /// let new_now = Instant::now();
    /// println!("{:?}", new_now.duration_since(now));
    /// ```
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn duration_since(&self, earlier: Instant) -> Duration {
        self.0.checked_sub_instant(&earlier.0).expect("supplied instant is later than self")
    }

    /// 返回从另一个时刻到该时刻所经过的时间; 如果该时刻晚于该时刻,则返回 None。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::time::{Duration, Instant};
    /// use std::thread::sleep;
    ///
    /// let now = Instant::now();
    /// sleep(Duration::new(1, 0));
    /// let new_now = Instant::now();
    /// println!("{:?}", new_now.checked_duration_since(now));
    /// println!("{:?}", now.checked_duration_since(new_now)); // None
    /// ```
    #[stable(feature = "checked_duration_since", since = "1.39.0")]
    pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> {
        self.0.checked_sub_instant(&earlier.0)
    }

    /// 返回从另一时刻到该时刻所经过的时间,如果该时刻晚于该时刻,则返回零持续时间。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::time::{Duration, Instant};
    /// use std::thread::sleep;
    ///
    /// let now = Instant::now();
    /// sleep(Duration::new(1, 0));
    /// let new_now = Instant::now();
    /// println!("{:?}", new_now.saturating_duration_since(now));
    /// println!("{:?}", now.saturating_duration_since(new_now)); // 0ns
    /// ```
    #[stable(feature = "checked_duration_since", since = "1.39.0")]
    pub fn saturating_duration_since(&self, earlier: Instant) -> Duration {
        self.checked_duration_since(earlier).unwrap_or_default()
    }

    /// 返回自创建此瞬间以来经过的时间。
    ///
    /// # Panics
    ///
    /// 如果当前时间早于此时刻,则此函数可能为 panic,如果 `Instant` 是综合生成的,则可能会发生这种情况。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::thread::sleep;
    /// use std::time::{Duration, Instant};
    ///
    /// let instant = Instant::now();
    /// let three_secs = Duration::from_secs(3);
    /// sleep(three_secs);
    /// assert!(instant.elapsed() >= three_secs);
    /// ```
    ///
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn elapsed(&self) -> Duration {
        Instant::now() - *self
    }

    /// 如果 `t` 可以表示为 `Instant` (表示它在基础数据结构体的边界之内),则返回 `Some(t)`,其中 `t` 是 `self + duration` 的时间,否则返回 `None`。
    ///
    ///
    #[stable(feature = "time_checked_add", since = "1.34.0")]
    pub fn checked_add(&self, duration: Duration) -> Option<Instant> {
        self.0.checked_add_duration(&duration).map(Instant)
    }

    /// 如果 `t` 可以表示为 `Instant` (表示它在基础数据结构体的边界之内),则返回 `Some(t)`,其中 `t` 是 `self - duration` 的时间,否则返回 `None`。
    ///
    ///
    #[stable(feature = "time_checked_add", since = "1.34.0")]
    pub fn checked_sub(&self, duration: Duration) -> Option<Instant> {
        self.0.checked_sub_duration(&duration).map(Instant)
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl Add<Duration> for Instant {
    type Output = Instant;

    /// # Panics
    ///
    /// 如果结果时间点不能由基础数据结构体表示,则此函数可能为 panic。
    /// 没有 panic 的版本,请参见 [`Instant::checked_add`]。
    fn add(self, other: Duration) -> Instant {
        self.checked_add(other).expect("overflow when adding duration to instant")
    }
}

#[stable(feature = "time_augmented_assignment", since = "1.9.0")]
impl AddAssign<Duration> for Instant {
    fn add_assign(&mut self, other: Duration) {
        *self = *self + other;
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl Sub<Duration> for Instant {
    type Output = Instant;

    fn sub(self, other: Duration) -> Instant {
        self.checked_sub(other).expect("overflow when subtracting duration from instant")
    }
}

#[stable(feature = "time_augmented_assignment", since = "1.9.0")]
impl SubAssign<Duration> for Instant {
    fn sub_assign(&mut self, other: Duration) {
        *self = *self - other;
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl Sub<Instant> for Instant {
    type Output = Duration;

    fn sub(self, other: Instant) -> Duration {
        self.duration_since(other)
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl fmt::Debug for Instant {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

impl SystemTime {
    /// 时间锚,可用于创建新的 `SystemTime` 实例或了解 `SystemTime` 的时间。
    ///
    /// 相对于系统时钟,此常量在所有系统上均定义为 "1970-01-01 00:00:00 UTC"。
    /// 在现有的 `SystemTime` 实例上使用 `duration_since` 可以告诉您测量距离该时间点有多远,并且可以使用 `UNIX_EPOCH + duration` 创建一个 `SystemTime` 实例来表示另一个固定的时间点。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::time::SystemTime;
    ///
    /// match SystemTime::now().duration_since(SystemTime::UNIX_EPOCH) {
    ///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
    ///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
    /// }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "assoc_unix_epoch", since = "1.28.0")]
    pub const UNIX_EPOCH: SystemTime = UNIX_EPOCH;

    /// 返回与 "now" 相对应的系统时间。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::time::SystemTime;
    ///
    /// let sys_time = SystemTime::now();
    /// ```
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn now() -> SystemTime {
        SystemTime(time::SystemTime::now())
    }

    /// 返回从较早的时间点过去的时间量。
    ///
    /// 此函数可能会失败,因为不能保证早先进行的测量总是在以后进行之前 (由于异常,例如向前或向后调整系统时钟)。
    ///
    /// [`Instant`] 可以用来测量经过的时间,而不会出现这种失败的风险。
    ///
    /// 如果成功,则返回 [`Ok`]`(`[`Duration`]`)`,其中持续时间表示从指定的度量到此度量所经过的时间。
    ///
    /// 如果 `earlier` 晚于 `self`,则返回 [`Err`],并且该错误包含时间与 `self` 的距离。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::time::SystemTime;
    ///
    /// let sys_time = SystemTime::now();
    /// let new_sys_time = SystemTime::now();
    /// let difference = new_sys_time.duration_since(sys_time)
    ///     .expect("Clock may have gone backwards");
    /// println!("{:?}", difference);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn duration_since(&self, earlier: SystemTime) -> Result<Duration, SystemTimeError> {
        self.0.sub_time(&earlier.0).map_err(SystemTimeError)
    }

    /// 返回创建此系统时间时的时钟时间与当前时钟时间之间的差。
    ///
    /// 由于底层系统时钟易于漂移和更新 (例如,系统时钟可能倒退),因此该函数可能会失败,因此此函数可能并不总是成功。
    /// 如果成功,则返回 [`Ok`]`(`[`Duration`]`)`,其中持续时间表示从该时间测量到当前时间所经过的时间。
    ///
    /// 为了可靠地测量经过时间,请改用 [`Instant`]。
    ///
    /// 如果 `self` 晚于当前系统时间,则返回 [`Err`],并且错误包含距当前系统时间 `self` 多远的时间。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::thread::sleep;
    /// use std::time::{Duration, SystemTime};
    ///
    /// let sys_time = SystemTime::now();
    /// let one_sec = Duration::from_secs(1);
    /// sleep(one_sec);
    /// assert!(sys_time.elapsed().unwrap() >= one_sec);
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn elapsed(&self) -> Result<Duration, SystemTimeError> {
        SystemTime::now().duration_since(*self)
    }

    /// 如果 `t` 可以表示为 `SystemTime` (表示它在基础数据结构体的边界之内),则返回 `Some(t)`,其中 `t` 是 `self + duration` 的时间,否则返回 `None`。
    ///
    ///
    #[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)
    }

    /// 如果 `t` 可以表示为 `SystemTime` (表示它在基础数据结构体的边界之内),则返回 `Some(t)`,其中 `t` 是 `self - duration` 的时间,否则返回 `None`。
    ///
    ///
    #[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)
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl Add<Duration> for SystemTime {
    type Output = SystemTime;

    /// # Panics
    ///
    /// 如果结果时间点不能由基础数据结构体表示,则此函数可能为 panic。
    /// 没有 panic 的版本,请参见 [`SystemTime::checked_add`]。
    fn add(self, dur: Duration) -> SystemTime {
        self.checked_add(dur).expect("overflow when adding duration to instant")
    }
}

#[stable(feature = "time_augmented_assignment", since = "1.9.0")]
impl AddAssign<Duration> for SystemTime {
    fn add_assign(&mut self, other: Duration) {
        *self = *self + other;
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl Sub<Duration> for SystemTime {
    type Output = SystemTime;

    fn sub(self, dur: Duration) -> SystemTime {
        self.checked_sub(dur).expect("overflow when subtracting duration from instant")
    }
}

#[stable(feature = "time_augmented_assignment", since = "1.9.0")]
impl SubAssign<Duration> for SystemTime {
    fn sub_assign(&mut self, other: Duration) {
        *self = *self - other;
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl fmt::Debug for SystemTime {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

/// 时间锚,可用于创建新的 `SystemTime` 实例或了解 `SystemTime` 的时间。
///
/// 相对于系统时钟,此常量在所有系统上均定义为 "1970-01-01 00:00:00 UTC"。
/// 在现有的 [`SystemTime`] 实例上使用 `duration_since` 可以告诉您测量距离该时间点有多远,并且可以使用 `UNIX_EPOCH + duration` 创建一个 [`SystemTime`] 实例来表示另一个固定的时间点。
///
///
/// # Examples
///
/// ```no_run
/// use std::time::{SystemTime, UNIX_EPOCH};
///
/// match SystemTime::now().duration_since(UNIX_EPOCH) {
///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
/// }
/// ```
///
///
///
#[stable(feature = "time2", since = "1.8.0")]
pub const UNIX_EPOCH: SystemTime = SystemTime(time::UNIX_EPOCH);

impl SystemTimeError {
    /// 返回正时长,它表示第二个系统时间与第一个系统时间相距多远。
    ///
    /// 每当第二个系统时间表示的时间晚于调用方法的 `self` 的时间点时,就会从 [`SystemTime::duration_since`] 和 [`SystemTime::elapsed`] 方法返回 `SystemTimeError`。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::thread::sleep;
    /// use std::time::{Duration, SystemTime};
    ///
    /// let sys_time = SystemTime::now();
    /// sleep(Duration::from_secs(1));
    /// let new_sys_time = SystemTime::now();
    /// match sys_time.duration_since(new_sys_time) {
    ///     Ok(_) => {}
    ///     Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn duration(&self) -> Duration {
        self.0
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl Error for SystemTimeError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "other time was not earlier than self"
    }
}

#[stable(feature = "time2", since = "1.8.0")]
impl fmt::Display for SystemTimeError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "second time provided was later than self")
    }
}

impl FromInner<time::SystemTime> for SystemTime {
    fn from_inner(time: time::SystemTime) -> SystemTime {
        SystemTime(time)
    }
}