//! 时间量化。
//!
//! # Examples
//!
//! 有多种方法可以创建新的 [`Duration`]：
//!
//! ```
//! # use std::time::Duration;
//! let five_seconds = Duration::from_secs(5);
//! assert_eq!(five_seconds, Duration::from_millis(5_000));
//! assert_eq!(five_seconds, Duration::from_micros(5_000_000));
//! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000));
//!
//! let ten_seconds = Duration::from_secs(10);
//! let seven_nanos = Duration::from_nanos(7);
//! let total = ten_seconds + seven_nanos;
//! assert_eq!(total, Duration::new(10, 7));
//! ```
//!
//! 使用 [`Instant`] 计算函数运行所需的时间：
//!
//! ```ignore (incomplete)
//! let now = Instant::now();
//!
//! // 调用慢函数可能需要一段时间
//! slow_function();
//!
//! let elapsed_time = now.elapsed();
//! println!("Running slow_function() took {} seconds.", elapsed_time.as_secs());
//! ```

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

#[cfg(test)]
mod tests;

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

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

#[stable(feature = "duration_checked_float", since = "1.66.0")]
pub use core::time::TryFromFloatSecsError;

/// 单调非递减时钟的度量。
/// 不透明且仅对 [`Duration`] 有用。
///
/// 除 [platform bugs] 外，时刻始终保证不低于任何先前测量的创建时的时刻，并且对于诸如测量基准或计时操作需要多长时间等任务通常很有用。
///
///
/// 但是请注意，不能保证 instants 是稳定的。换句话说，底层时钟的每个滴答声的长度可能不同 (例如
/// 几秒钟可能比其他更长)。瞬间可能会向前跳跃或经历时间膨胀 (减速或加速)，但永远不会向后退。
///
/// 即时消息是不透明的类型，只能相互比较。没有方法可以立即获取 "秒数"。
/// 相反，它仅允许测量两个瞬间之间的持续时间 (或比较两个瞬间)。
///
/// `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());
/// }
/// ```
///
/// [platform bugs]: Instant#monotonicity
///
/// # 特定于操作系统的行为
///
/// `Instant` 是系统特定类型的包装器，根据底层操作系统的不同，它的行为可能会有所不同。
/// 例如，以下代码段在 Linux 上很好，但在 macOS 上为 panics：
///
/// ```no_run
/// use std::time::{Instant, Duration};
///
/// let now = Instant::now();
/// let max_seconds = u64::MAX / 1_000_000_000;
/// let duration = Duration::new(max_seconds, 0);
/// println!("{:?}", now + duration);
/// ```
///
/// # 底层系统调用
///
/// 以下系统调用是 `now()` 使用 [currently] 来找出当前时间:
///
/// |  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)]                                    |
/// | SOLID     | `get_tim`                                                            |
/// | WASI      | [__wasi_clock_time_get (Monotonic Clock)]                            |
/// | Windows   | [QueryPerformanceCounter]                                            |
///
/// [currently]: crate::io#platform-specific-behavior
/// [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/main/legacy/preview1/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
///
/// ## Monotonicity
///
/// 在所有平台上，`Instant` 将尝试使用保证单调行为 (如果可用) 的 OS API，所有 [tier 1] 平台都是这种情况。
/// 在实践中，这种保证在极少数情况下会被硬件、虚拟化或操作系统错误破坏。
/// 为了解决这些错误和不提供单调时钟的平台，[`duration_since`]、[`elapsed`] 和 [`sub`] 饱和为零。
/// 在较旧的 Rust 版本中，这反而会导致 panic。
/// [`checked_duration_since`] 可用于检测和处理违反单调性或以错误顺序减去 `即时` 的情况。
///
/// 这种变通方法掩盖了早期和后期瞬间意外交换的编程错误。出于这个原因，未来的 rust 版本可能会重新引入 panic。
///
/// [tier 1]: https://doc.rust-lang.org/rustc/platform-support.html
/// [`duration_since`]: Instant::duration_since
/// [`elapsed`]: Instant::elapsed
/// [`sub`]: Instant::sub
/// [`checked_duration_since`]: Instant::checked_duration_since
///
///
///
///
///
///
///
///
///
///
///
///
///
#[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:?}");
///        }
///    }
/// }
/// ```
///
/// # 特定于平台的行为
///
/// `SystemTime` 的精度可能取决于底层操作系统特定的时间格式。
/// 例如，在 Windows 上，时间以 100 纳秒间隔表示，而 Linux 可以表示纳秒间隔。
///
/// 以下系统调用是 `now()` 使用 [currently] 来找出当前时间:
///
/// |  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)]                                     |
/// | SOLID     | `SOLID_RTC_ReadTime`                                                 |
/// | WASI      | [__wasi_clock_time_get (Realtime Clock)]                             |
/// | Windows   | [GetSystemTimePreciseAsFileTime] / [GetSystemTimeAsFileTime]         |
///
/// [currently]: crate::io#platform-specific-behavior
/// [`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/main/legacy/preview1/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();
    /// ```
    #[must_use]
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn now() -> Instant {
        Instant(time::Instant::now())
    }

    /// 返回从另一时刻到该时刻所经过的时间，如果该时刻晚于该时刻，则返回零持续时间。
    ///
    ///
    /// # Panics
    ///
    /// 当 `earlier` 晚于 `self` 时，以前的 rust 版本会出现 panic。目前这种方法已经饱和。
    /// 未来的版本在某些情况下可能会重新引入 panic。
    /// 请参见 [Monotonicity]。
    ///
    /// [Monotonicity]: Instant#monotonicity
    ///
    /// # 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));
    /// println!("{:?}", now.duration_since(new_now)); // 0ns
    /// ```
    #[must_use]
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn duration_since(&self, earlier: Instant) -> Duration {
        self.checked_duration_since(earlier).unwrap_or_default()
    }

    /// 返回从另一个时刻到该时刻所经过的时间; 如果该时刻晚于该时刻，则返回 None。
    ///
    /// 由于 [monotonicity bugs]，即使在传递的 `Instant` 的正确逻辑顺序下，此方法也可以返回 `None`。
    ///
    ///
    /// [monotonicity bugs]: Instant#monotonicity
    ///
    /// # 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
    /// ```
    ///
    #[must_use]
    #[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
    /// ```
    #[must_use]
    #[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
    ///
    /// 当前时间早于自己时，以前的 rust 版本会出现 panic。目前，在这种情况下，此方法返回的 Duration 为零。
    /// 未来的版本可能会重新引入 panic。
    /// 请参见 [Monotonicity]。
    ///
    /// [Monotonicity]: Instant#monotonicity
    ///
    /// # 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);
    /// ```
    #[must_use]
    #[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;

    /// 返回从另一时刻到该时刻所经过的时间，如果该时刻晚于该时刻，则返回零持续时间。
    ///
    ///
    /// # Panics
    ///
    /// 当 `other` 晚于 `self` 时，以前的 rust 版本会出现 panic。目前这种方法已经饱和。
    /// 未来的版本在某些情况下可能会重新引入 panic。
    /// 请参见 [Monotonicity]。
    ///
    /// [Monotonicity]: Instant#monotonicity
    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();
    /// ```
    #[must_use]
    #[stable(feature = "time2", since = "1.8.0")]
    pub fn now() -> SystemTime {
        SystemTime(time::SystemTime::now())
    }

    /// 返回从较早的时间点过去的时间量。
    ///
    /// 此函数可能会失败，因为不能保证早先进行的测量总是在以后进行之前 (由于异常，例如向前或向后调整系统时钟)。
    ///
    /// [`Instant`] 可用于测量经过的时间，而不会出现这种故障风险。
    ///
    /// 如果成功，则返回 <code>[Ok]\([Duration])</code>，其中持续时间表示从指定测量到此测量所经过的时间。
    ///
    /// 如果 `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)
    }

    /// 返回此系统时间与当前时钟时间的差异。
    ///
    /// 这个函数可能会失败，因为底层系统时钟容易受到漂移和更新的影响 (例如，系统时钟可能会倒退)，所以这个函数可能并不总是成功。
    /// 如果成功，则返回 <code>[Ok]\([Duration])</code>，其中持续时间表示从这次时间测量到当前时间所经过的时间。
    ///
    /// 为了可靠地测量经过时间，请改用 [`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()),
    /// }
    /// ```
    ///
    ///
    #[must_use]
    #[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)
    }
}

impl IntoInner<time::SystemTime> for SystemTime {
    fn into_inner(self) -> time::SystemTime {
        self.0
    }
}