#[cfg(test)]
mod tests;

#[cfg(target_pointer_width = "64")]
mod repr_bitpacked;
#[cfg(target_pointer_width = "64")]
use repr_bitpacked::Repr;

#[cfg(not(target_pointer_width = "64"))]
mod repr_unpacked;
#[cfg(not(target_pointer_width = "64"))]
use repr_unpacked::Repr;

use crate::error;
use crate::fmt;
use crate::result;
use crate::sys;

/// I/O 操作的专用 [`Result`] 类型。
///
/// [`std::io`] 广泛使用此类型进行可能产生错误的任何操作。
///
/// 通常使用这种 typedef 来避免直接写出 [`io::Error`]，否则直接映射到 [`Result`]。
///
/// 通常的 Rust 样式是直接导入类型，而 [`Result`] 的别名通常不是，以便于区分它们。
/// [`Result`] 通常被假定为 [`std::result::Result`][`Result`]，因此这个别名的用户通常会使用 `io::Result` 而不是隐藏 [prelude] 对 [`std::result::Result`][`Result`] 的导入。
///
///
/// [`std::io`]: crate::io
/// [`io::Error`]: Error
/// [`Result`]: crate::result::Result
/// [prelude]: crate::prelude
///
/// # Examples
///
/// 一个方便的函数，将 `io::Result` 冒泡给其调用者：
///
/// ```
/// use std::io;
///
/// fn get_string() -> io::Result<String> {
///     let mut buffer = String::new();
///
///     io::stdin().read_line(&mut buffer)?;
///
///     Ok(buffer)
/// }
/// ```
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub type Result<T> = result::Result<T, Error>;

/// [`Read`]，[`Write`]，[`Seek`] 和关联的 traits 的 I/O 操作的错误类型。
///
/// 错误主要来自底层操作系统，但可以使用精心制作的错误消息和特定的 [`ErrorKind`] 值来创建 `Error` 的自定义实例。
///
///
/// [`Read`]: crate::io::Read
/// [`Write`]: crate::io::Write
/// [`Seek`]: crate::io::Seek
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Error {
    repr: Repr,
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&self.repr, f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl From<alloc::ffi::NulError> for Error {
    /// 将 [`alloc::ffi::NulError`] 转换为 [`Error`]。
    fn from(_: alloc::ffi::NulError) -> Error {
        const_io_error!(ErrorKind::InvalidInput, "data provided contains a nul byte")
    }
}

// 仅在测试中派生调试，以确保它不会意外打印。
//
#[cfg_attr(test, derive(Debug))]
enum ErrorData<C> {
    Os(RawOsError),
    Simple(ErrorKind),
    SimpleMessage(&'static SimpleMessage),
    Custom(C),
}

/// [`Error::raw_os_error`] 返回的原始操作系统错误代码的类型。
///
/// 这是所有当前支持的平台上的 [`i32`]，但在 future 中添加的平台 (例如 UEFI) 可能会使用不同的原始类型，例如 [`usize`]。
/// 在适用的情况下使用 as 或 [`into`] 转换以确保最大的可移植性。
///
/// [`into`]: Into::into
///
///
#[unstable(feature = "raw_os_error_ty", issue = "107792")]
pub type RawOsError = i32;

// `#[repr(align(4))]` 可能是多余的，它应该已经具有该值或更高的值。我们包含它只是因为 repr_bitpacked.rs 的编码需要对齐 >= 4 (注意 `#[repr(align)]` 不会减少结构体所需的对齐，只会增加它)。
//
// 如果我们向 ErrorData 添加更多变体，这可以增加到 8，但它可能应该在 `#[cfg_attr(target_pointer_width = "64", ...)]` 或我们用来启用 `repr_bitpacked` 代码的任何 cfg 之后，因为只有那个版本需要对齐，并且 8 高于我们将在 32 位平台上进行对齐。
//
//
// (为了明确起见：这里的对齐要求只有在使用 `error/repr_bitpacked.rs` 时才重要 -- 对于解包的 repr 来说根本不重要)
//
//
//
//
//
//
//
//
#[repr(align(4))]
#[derive(Debug)]
pub(crate) struct SimpleMessage {
    kind: ErrorKind,
    message: &'static str,
}

impl SimpleMessage {
    pub(crate) const fn new(kind: ErrorKind, message: &'static str) -> Self {
        Self { kind, message }
    }
}

/// 为给定的 `ErrorKind` 和常量消息创建并返回 `io::Error`。
/// 这个不分配。
pub(crate) macro const_io_error($kind:expr, $message:expr $(,)?) {
    $crate::io::error::Error::from_static_message({
        const MESSAGE_DATA: $crate::io::error::SimpleMessage =
            $crate::io::error::SimpleMessage::new($kind, $message);
        &MESSAGE_DATA
    })
}

// 与 `SimpleMessage` 一样：这里的 `#[repr(align(4))]` 只是因为 repr_bitpacked 的编码需要它。
// 在实践中，几乎可以肯定，它已经达到或超过了这个水平。
//
#[derive(Debug)]
#[repr(align(4))]
struct Custom {
    kind: ErrorKind,
    error: Box<dyn error::Error + Send + Sync>,
}

/// 一个列表，指定 I/O 错误的常规类别。
///
/// 此列表旨在随着时间的增长而增长，不建议对其进行详尽的匹配。
///
/// 与 [`io::Error`] 类型一起使用。
///
/// [`io::Error`]: Error
///
/// # 在 `ErrorKind` 上处理错误和匹配
///
/// 在应用程序代码中，使用 `match` 作为您期望的 `ErrorKind` 值; 使用 `_` 匹配 "所有其他错误"。
///
/// 在想要验证测试不会返回任何已知的不正确错误类型的全面而彻底的测试中，您可能需要将当前完整的错误列表从此处剪切并粘贴到您的测试代码中，然后将 `_` 匹配为正确的情况。
/// 这似乎违反直觉，但它会使您的测试更加健壮。
/// 特别是，如果您想验证您的代码确实产生了无法识别的错误类型，那么可靠的解决方案是检查所有已识别的错误类型并在这些情况下失败。
///
///
///
///
///
///
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated)]
#[non_exhaustive]
pub enum ErrorKind {
    /// 找不到实体，通常是文件。
    #[stable(feature = "rust1", since = "1.0.0")]
    NotFound,
    /// 该操作缺少完成操作所需的权限。
    #[stable(feature = "rust1", since = "1.0.0")]
    PermissionDenied,
    /// 远程服务器拒绝了连接。
    #[stable(feature = "rust1", since = "1.0.0")]
    ConnectionRefused,
    /// 连接已由远程服务器重置。
    #[stable(feature = "rust1", since = "1.0.0")]
    ConnectionReset,
    /// 远程主机不可访问。
    #[unstable(feature = "io_error_more", issue = "86442")]
    HostUnreachable,
    /// 无法访问包含远程主机的网络。
    #[unstable(feature = "io_error_more", issue = "86442")]
    NetworkUnreachable,
    /// (terminated) 连接被远程服务器中止。
    #[stable(feature = "rust1", since = "1.0.0")]
    ConnectionAborted,
    /// 网络操作失败，因为尚未连接。
    #[stable(feature = "rust1", since = "1.0.0")]
    NotConnected,
    /// 无法绑定套接字地址，因为该地址已在其他地方使用。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    AddrInUse,
    /// 请求了不存在的接口，或者请求的地址不是本地的。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    AddrNotAvailable,
    /// 系统的网络已关闭。
    #[unstable(feature = "io_error_more", issue = "86442")]
    NetworkDown,
    /// 操作失败，因为管道已关闭。
    #[stable(feature = "rust1", since = "1.0.0")]
    BrokenPipe,
    /// 一个实体已经存在，通常是一个文件。
    #[stable(feature = "rust1", since = "1.0.0")]
    AlreadyExists,
    /// 该操作需要阻止才能完成，但是请求阻止操作不会发生。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    WouldBlock,
    /// 出乎意料的是，文件系统对象不是目录。
    ///
    /// 例如，指定了一个文件系统路径，其中一个中间目录组件实际上是一个普通文件。
    ///
    #[unstable(feature = "io_error_more", issue = "86442")]
    NotADirectory,
    /// 出乎意料的是，文件系统对象是一个目录。
    ///
    /// 当需要一个非目录时指定了一个目录。
    #[unstable(feature = "io_error_more", issue = "86442")]
    IsADirectory,
    /// 在需要空目录的地方指定了一个非空目录。
    #[unstable(feature = "io_error_more", issue = "86442")]
    DirectoryNotEmpty,
    /// 文件系统或存储介质是只读的，但尝试了写入操作。
    #[unstable(feature = "io_error_more", issue = "86442")]
    ReadOnlyFilesystem,
    /// 在文件系统或 IO 子系统中循环； 通常，太多级别的符号链接。
    ///
    /// 有一个循环 (或过长的链) 解析文件系统对象或文件 IO 对象。
    ///
    /// 在 Unix 上，这通常是符号链接循环的结果； 或者，超过系统特定的符号链接遍历深度限制。
    ///
    ///
    #[unstable(feature = "io_error_more", issue = "86442")]
    FilesystemLoop,
    /// 陈旧的网络文件句柄。
    ///
    /// 对于某些网络文件系统，尤其是 NFS，打开的文件 (或目录) 可能会因网络或服务器问题而失效。
    ///
    #[unstable(feature = "io_error_more", issue = "86442")]
    StaleNetworkFileHandle,
    /// 参数不正确。
    #[stable(feature = "rust1", since = "1.0.0")]
    InvalidInput,
    /// 遇到对该操作无效的数据。
    ///
    /// 与 [`InvalidInput`] 不同，这通常意味着操作参数有效，但是该错误是由格式错误的输入数据引起的。
    ///
    ///
    /// 例如，如果文件的内容无效 UTF-8，则将文件读入字符串的函数将出现 `InvalidData` 错误。
    ///
    /// [`InvalidInput`]: ErrorKind::InvalidInput
    ///
    ///
    #[stable(feature = "io_invalid_data", since = "1.2.0")]
    InvalidData,
    /// I/O 操作的超时已到期，导致其被取消。
    #[stable(feature = "rust1", since = "1.0.0")]
    TimedOut,
    /// 由于调用 [`write`] 返回 [`Ok(0)`] 而无法完成操作时，返回错误。
    ///
    /// 这通常意味着操作只有在写入特定数量的字节后才能成功，但是只能写入较少的字节数才能成功。
    ///
    ///
    /// [`write`]: crate::io::Write::write
    /// [`Ok(0)`]: Ok
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    WriteZero,
    /// 底层存储 (通常是文件系统) 已满。
    ///
    /// 这不包括超出配额的错误。
    #[unstable(feature = "io_error_more", issue = "86442")]
    StorageFull,
    /// Seek 在不可搜索的文件上。
    ///
    /// 尝试在不适合搜索的打开文件句柄上进行搜索 - 例如，在 Unix 上，使用 `File::open` 打开的命名管道。
    ///
    #[unstable(feature = "io_error_more", issue = "86442")]
    NotSeekable,
    /// 超出了文件系统配额。
    #[unstable(feature = "io_error_more", issue = "86442")]
    FilesystemQuotaExceeded,
    /// 文件大于允许或支持。
    ///
    /// 这可能源于底层文件系统或文件访问 API 的硬限制，或源于管理强加的资源限制。
    /// 简单的磁盘已满，超出配额，都有自己的错误。
    ///
    #[unstable(feature = "io_error_more", issue = "86442")]
    FileTooLarge,
    /// 资源繁忙。
    #[unstable(feature = "io_error_more", issue = "86442")]
    ResourceBusy,
    /// 可执行文件正忙。
    ///
    /// 试图写入一个文件，该文件也用作正在运行的程序。
    /// (并非所有操作系统都检测到这种情况。)
    #[unstable(feature = "io_error_more", issue = "86442")]
    ExecutableFileBusy,
    /// 死锁 (avoided)。
    ///
    /// 文件锁定操作会导致死锁。
    /// 这种情况通常是在尽力而为的基础上检测到的。
    #[unstable(feature = "io_error_more", issue = "86442")]
    Deadlock,
    /// 跨设备或跨文件系统 (hard) 链接或重命名。
    #[unstable(feature = "io_error_more", issue = "86442")]
    CrossesDevices,
    /// 太多 (hard) 链接到同一个文件系统对象。
    ///
    /// 文件系统不支持对同一个文件建立如此多的硬链接。
    #[unstable(feature = "io_error_more", issue = "86442")]
    TooManyLinks,
    /// 文件名无效。
    ///
    /// 如果超出文件名长度限制，也会导致此错误。
    #[unstable(feature = "io_error_more", issue = "86442")]
    InvalidFilename,
    /// 程序参数列表太长。
    ///
    /// 尝试运行外部程序时，会超出系统或进程对参数大小的限制。
    ///
    #[unstable(feature = "io_error_more", issue = "86442")]
    ArgumentListTooLong,
    /// 该操作被中断。
    ///
    /// 通常可以重试中断的操作。
    #[stable(feature = "rust1", since = "1.0.0")]
    Interrupted,

    /// 此平台不支持此操作。
    ///
    /// 这意味着操作永远不会成功。
    #[stable(feature = "unsupported_error", since = "1.53.0")]
    Unsupported,

    // ErrorKinds 主要是 OS 错误代码的分类应在上面添加。
    //
    //
    /// 由于过早到达 "文件结尾" 而无法完成操作时，返回错误。
    ///
    /// 通常，这意味着操作只有在读取特定数量的字节后才能成功，但是只能读取较少的字节。
    ///
    ///
    ///
    #[stable(feature = "read_exact", since = "1.6.0")]
    UnexpectedEof,

    /// 操作无法完成，因为它未能分配足够的内存。
    ///
    #[stable(feature = "out_of_memory_error", since = "1.54.0")]
    OutOfMemory,

    // "Unusual" 错误类型不只对应于 (组) 操作系统错误代码，应添加在这个注释的正上方。
    //
    // `Other` 和 `Uncategorized` 应该保留在最后:
    //
    /// 不属于任何其他 I/O 错误类型的自定义错误。
    ///
    /// 这可用于构建您自己的不匹配任何 [`ErrorKind`] 的 [`Error`]。
    ///
    /// 标准库不使用此 [`ErrorKind`]。
    ///
    /// 标准库中不属于任何 I/O 错误类型的错误无法 `匹配`，并且只会匹配通配符 (`_`) 模式。
    ///
    /// 可能会在 future 中为其中一些添加新的 [`ErrorKind`]。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Other,

    /// 标准库中不属于此列表的任何 I/O 错误。
    ///
    /// 现在 `Uncategorized` 的错误将来可能会转移到不同的或新的 [`ErrorKind`] 变体。
    /// 不建议针对 `Uncategorized` 匹配错误； 改用通配符匹配 (`_`)。
    ///
    #[unstable(feature = "io_error_uncategorized", issue = "none")]
    #[doc(hidden)]
    Uncategorized,
}

impl ErrorKind {
    pub(crate) fn as_str(&self) -> &'static str {
        use ErrorKind::*;
        // tidy-alphabetical-start
        match *self {
            AddrInUse => "address in use",
            AddrNotAvailable => "address not available",
            AlreadyExists => "entity already exists",
            ArgumentListTooLong => "argument list too long",
            BrokenPipe => "broken pipe",
            ConnectionAborted => "connection aborted",
            ConnectionRefused => "connection refused",
            ConnectionReset => "connection reset",
            CrossesDevices => "cross-device link or rename",
            Deadlock => "deadlock",
            DirectoryNotEmpty => "directory not empty",
            ExecutableFileBusy => "executable file busy",
            FileTooLarge => "file too large",
            FilesystemLoop => "filesystem loop or indirection limit (e.g. symlink loop)",
            FilesystemQuotaExceeded => "filesystem quota exceeded",
            HostUnreachable => "host unreachable",
            Interrupted => "operation interrupted",
            InvalidData => "invalid data",
            InvalidFilename => "invalid filename",
            InvalidInput => "invalid input parameter",
            IsADirectory => "is a directory",
            NetworkDown => "network down",
            NetworkUnreachable => "network unreachable",
            NotADirectory => "not a directory",
            NotConnected => "not connected",
            NotFound => "entity not found",
            NotSeekable => "seek on unseekable file",
            Other => "other error",
            OutOfMemory => "out of memory",
            PermissionDenied => "permission denied",
            ReadOnlyFilesystem => "read-only filesystem or storage medium",
            ResourceBusy => "resource busy",
            StaleNetworkFileHandle => "stale network file handle",
            StorageFull => "no storage space",
            TimedOut => "timed out",
            TooManyLinks => "too many links",
            Uncategorized => "uncategorized error",
            UnexpectedEof => "unexpected end of file",
            Unsupported => "unsupported",
            WouldBlock => "operation would block",
            WriteZero => "write zero",
        }
        // tidy-alphabetical-end
    }
}

#[stable(feature = "io_errorkind_display", since = "1.60.0")]
impl fmt::Display for ErrorKind {
    /// 显示了对 `ErrorKind` 的可读描述。
    ///
    /// 这类似于 `impl Display for Error`，但不需要先转换为 Error。
    ///
    /// # Examples
    /// ```
    /// use std::io::ErrorKind;
    /// assert_eq!("entity not found", ErrorKind::NotFound.to_string());
    /// ```
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str(self.as_str())
    }
}

/// 旨在用于未暴露给用户的错误，因为分配到堆上 (通过 Error::new 进行常规构建) 的代价太高了。
///
#[stable(feature = "io_error_from_errorkind", since = "1.14.0")]
impl From<ErrorKind> for Error {
    /// 将 [`ErrorKind`] 转换为 [`Error`]。
    ///
    /// 这种转换会创建一个带有错误类型的简单表示的新错误。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{Error, ErrorKind};
    ///
    /// let not_found = ErrorKind::NotFound;
    /// let error = Error::from(not_found);
    /// assert_eq!("entity not found", format!("{error}"));
    /// ```
    #[inline]
    fn from(kind: ErrorKind) -> Error {
        Error { repr: Repr::new_simple(kind) }
    }
}

impl Error {
    /// 根据已知的错误以及任意的错误有效载荷创建新的 I/O 错误。
    ///
    /// 此函数通常用于创建 I/O 错误，这些错误并非源于操作系统本身。
    /// `error` 参数是将包含在此 [`Error`] 中的任意有效载荷。
    ///
    /// 请注意，此函数在堆上分配内存。
    /// 如果不需要额外的有效载荷，请使用来自 `ErrorKind` 的 `From` 转换。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{Error, ErrorKind};
    ///
    /// // 可以从字符串创建错误
    /// let custom_error = Error::new(ErrorKind::Other, "oh no!");
    ///
    /// // 错误也可以从其他错误中创建
    /// let custom_error2 = Error::new(ErrorKind::Interrupted, custom_error);
    ///
    /// // 在没有有效，载荷 (并且没有内存分配) 的情况下创建错误
    /// let eof_error = Error::from(ErrorKind::UnexpectedEof);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn new<E>(kind: ErrorKind, error: E) -> Error
    where
        E: Into<Box<dyn error::Error + Send + Sync>>,
    {
        Self::_new(kind, error.into())
    }

    /// 从任意错误有效载荷创建新的 I/O 错误。
    ///
    /// 此函数通常用于创建 I/O 错误，这些错误并非源于操作系统本身。
    /// 它是 [`Error::new`] 与 [`ErrorKind::Other`] 的快捷方式。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(io_error_other)]
    ///
    /// use std::io::Error;
    ///
    /// // 可以从字符串创建错误
    /// let custom_error = Error::other("oh no!");
    ///
    /// // 错误也可以从其他错误中创建
    /// let custom_error2 = Error::other(custom_error);
    /// ```
    ///
    #[unstable(feature = "io_error_other", issue = "91946")]
    pub fn other<E>(error: E) -> Error
    where
        E: Into<Box<dyn error::Error + Send + Sync>>,
    {
        Self::_new(ErrorKind::Other, error.into())
    }

    fn _new(kind: ErrorKind, error: Box<dyn error::Error + Send + Sync>) -> Error {
        Error { repr: Repr::new_custom(Box::new(Custom { kind, error })) }
    }

    /// 从已知类型的错误以及恒定消息创建一个新的 I/O 错误。
    ///
    /// 这个函数不分配。
    ///
    /// 您不应该直接使用它，而应使用 `const_io_error!` 宏: `io::const_io_error!(ErrorKind::Something, "some_message")`。
    ///
    /// 将来，当 const 泛型允许时，这个函数可能会更改为 `from_static_message<const MSG: &'static str>(kind: ErrorKind)`。
    ///
    ///
    ///
    #[inline]
    pub(crate) const fn from_static_message(msg: &'static SimpleMessage) -> Error {
        Self { repr: Repr::new_simple_message(msg) }
    }

    /// 返回代表最近发生的操作系统错误的错误。
    ///
    /// 该函数读取目标平台的 `errno` 值 (例如，
    /// Windows 上的 `GetLastError`) 并将为错误代码返回相应的 [`Error`] 实例。
    ///
    /// 这应该在调用到平台函数之后立即调用，否则错误值的状态是不确定的。
    /// 特别是，其他标准库函数可能会调用平台函数，即使它们成功也可能 (或可能不会) 重置错误值。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::Error;
    ///
    /// let os_error = Error::last_os_error();
    /// println!("last OS error: {os_error:?}");
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[doc(alias = "GetLastError")]
    #[doc(alias = "errno")]
    #[must_use]
    #[inline]
    pub fn last_os_error() -> Error {
        Error::from_raw_os_error(sys::os::errno())
    }

    /// 根据特定的操作系统错误代码创建 [`Error`] 的新实例。
    ///
    /// # Examples
    ///
    /// 在 Linux 上：
    ///
    /// ```
    /// # if cfg!(target_os = "linux") {
    /// use std::io;
    ///
    /// let error = io::Error::from_raw_os_error(22);
    /// assert_eq!(error.kind(), io::ErrorKind::InvalidInput);
    /// # }
    /// ```
    ///
    /// 在 Windows 上：
    ///
    /// ```
    /// # if cfg!(windows) {
    /// use std::io;
    ///
    /// let error = io::Error::from_raw_os_error(10022);
    /// assert_eq!(error.kind(), io::ErrorKind::InvalidInput);
    /// # }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    #[inline]
    pub fn from_raw_os_error(code: RawOsError) -> Error {
        Error { repr: Repr::new_os(code) }
    }

    /// 返回此错误表示的操作系统错误 (如果有)。
    ///
    /// 如果此 [`Error`] 是通过 [`last_os_error`] 或 [`from_raw_os_error`] 构造的，则此函数将返回 [`Some`]，否则它将返回 [`None`]。
    ///
    ///
    /// [`last_os_error`]: Error::last_os_error
    /// [`from_raw_os_error`]: Error::from_raw_os_error
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{Error, ErrorKind};
    ///
    /// fn print_os_error(err: &Error) {
    ///     if let Some(raw_os_err) = err.raw_os_error() {
    ///         println!("raw OS error: {raw_os_err:?}");
    ///     } else {
    ///         println!("Not an OS error");
    ///     }
    /// }
    ///
    /// fn main() {
    ///     // 将打印 "raw OS error: ..."。
    ///     print_os_error(&Error::last_os_error());
    ///     // 将打印 "Not an OS error"。
    ///     print_os_error(&Error::new(ErrorKind::Other, "oh no!"));
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    #[inline]
    pub fn raw_os_error(&self) -> Option<RawOsError> {
        match self.repr.data() {
            ErrorData::Os(i) => Some(i),
            ErrorData::Custom(..) => None,
            ErrorData::Simple(..) => None,
            ErrorData::SimpleMessage(..) => None,
        }
    }

    /// 返回对此错误包装的内部错误 (如果有) 的引用。
    ///
    /// 如果此 [`Error`] 是通过 [`new`] 构造的，则此函数将返回 [`Some`]，否则它将返回 [`None`]。
    ///
    ///
    /// [`new`]: Error::new
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{Error, ErrorKind};
    ///
    /// fn print_error(err: &Error) {
    ///     if let Some(inner_err) = err.get_ref() {
    ///         println!("Inner error: {inner_err:?}");
    ///     } else {
    ///         println!("No inner error");
    ///     }
    /// }
    ///
    /// fn main() {
    ///     // 将打印 "No inner error"。
    ///     print_error(&Error::last_os_error());
    ///     // 将打印 "Inner error: ..."。
    ///     print_error(&Error::new(ErrorKind::Other, "oh no!"));
    /// }
    /// ```
    #[stable(feature = "io_error_inner", since = "1.3.0")]
    #[must_use]
    #[inline]
    pub fn get_ref(&self) -> Option<&(dyn error::Error + Send + Sync + 'static)> {
        match self.repr.data() {
            ErrorData::Os(..) => None,
            ErrorData::Simple(..) => None,
            ErrorData::SimpleMessage(..) => None,
            ErrorData::Custom(c) => Some(&*c.error),
        }
    }

    /// 返回对此错误包装的内部错误的可变引用 (如果有)。
    ///
    /// 如果此 [`Error`] 是通过 [`new`] 构造的，则此函数将返回 [`Some`]，否则它将返回 [`None`]。
    ///
    ///
    /// [`new`]: Error::new
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{Error, ErrorKind};
    /// use std::{error, fmt};
    /// use std::fmt::Display;
    ///
    /// #[derive(Debug)]
    /// struct MyError {
    ///     v: String,
    /// }
    ///
    /// impl MyError {
    ///     fn new() -> MyError {
    ///         MyError {
    ///             v: "oh no!".to_string()
    ///         }
    ///     }
    ///
    ///     fn change_message(&mut self, new_message: &str) {
    ///         self.v = new_message.to_string();
    ///     }
    /// }
    ///
    /// impl error::Error for MyError {}
    ///
    /// impl Display for MyError {
    ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         write!(f, "MyError: {}", &self.v)
    ///     }
    /// }
    ///
    /// fn change_error(mut err: Error) -> Error {
    ///     if let Some(inner_err) = err.get_mut() {
    ///         inner_err.downcast_mut::<MyError>().unwrap().change_message("I've been changed!");
    ///     }
    ///     err
    /// }
    ///
    /// fn print_error(err: &Error) {
    ///     if let Some(inner_err) = err.get_ref() {
    ///         println!("Inner error: {inner_err}");
    ///     } else {
    ///         println!("No inner error");
    ///     }
    /// }
    ///
    /// fn main() {
    ///     // 将打印 "No inner error"。
    ///     print_error(&change_error(Error::last_os_error()));
    ///     // 将打印 "Inner error: ..."。
    ///     print_error(&change_error(Error::new(ErrorKind::Other, MyError::new())));
    /// }
    /// ```
    ///
    #[stable(feature = "io_error_inner", since = "1.3.0")]
    #[must_use]
    #[inline]
    pub fn get_mut(&mut self) -> Option<&mut (dyn error::Error + Send + Sync + 'static)> {
        match self.repr.data_mut() {
            ErrorData::Os(..) => None,
            ErrorData::Simple(..) => None,
            ErrorData::SimpleMessage(..) => None,
            ErrorData::Custom(c) => Some(&mut *c.error),
        }
    }

    /// 消耗 `Error`，并返回其内部错误 (如果有)。
    ///
    /// 如果此 [`Error`] 是通过 [`new`] 构造的，则此函数将返回 [`Some`]，否则它将返回 [`None`]。
    ///
    ///
    /// [`new`]: Error::new
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{Error, ErrorKind};
    ///
    /// fn print_error(err: Error) {
    ///     if let Some(inner_err) = err.into_inner() {
    ///         println!("Inner error: {inner_err}");
    ///     } else {
    ///         println!("No inner error");
    ///     }
    /// }
    ///
    /// fn main() {
    ///     // 将打印 "No inner error"。
    ///     print_error(Error::last_os_error());
    ///     // 将打印 "Inner error: ..."。
    ///     print_error(Error::new(ErrorKind::Other, "oh no!"));
    /// }
    /// ```
    #[stable(feature = "io_error_inner", since = "1.3.0")]
    #[must_use = "`self` will be dropped if the result is not used"]
    #[inline]
    pub fn into_inner(self) -> Option<Box<dyn error::Error + Send + Sync>> {
        match self.repr.into_data() {
            ErrorData::Os(..) => None,
            ErrorData::Simple(..) => None,
            ErrorData::SimpleMessage(..) => None,
            ErrorData::Custom(c) => Some(c.error),
        }
    }

    /// 尝试将内部错误降级为 `E` (如果有)。
    ///
    /// 如果这个 [`Error`] 是通过 [`new`] 构建的，那么这个函数将尝试对其执行降级，否则它将返回 [`Err`]。
    ///
    ///
    /// 降级成功返回 [`Ok`]，否则返回 [`Err`]。
    ///
    /// [`new`]: Error::new
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(io_error_downcast)]
    ///
    /// use std::fmt;
    /// use std::io;
    /// use std::error::Error;
    ///
    /// #[derive(Debug)]
    /// enum E {
    ///     Io(io::Error),
    ///     SomeOtherVariant,
    /// }
    ///
    /// impl fmt::Display for E {
    ///    // ...
    /// #    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    /// #        todo!()
    /// #    }
    /// }
    /// impl Error for E {}
    ///
    /// impl From<io::Error> for E {
    ///     fn from(err: io::Error) -> E {
    ///         err.downcast::<E>()
    ///             .map(|b| *b)
    ///             .unwrap_or_else(E::Io)
    ///     }
    /// }
    /// ```
    ///
    #[unstable(feature = "io_error_downcast", issue = "99262")]
    pub fn downcast<E>(self) -> result::Result<Box<E>, Self>
    where
        E: error::Error + Send + Sync + 'static,
    {
        match self.repr.into_data() {
            ErrorData::Custom(b) if b.error.is::<E>() => {
                let res = (*b).error.downcast::<E>();

                // downcast 真的很琐碎，并且被标记为内联，所以它很可能在这里被内联。
                //
                // 并且编译器应该能够消除这里产生 `Err` 的分支，因为 b.error.is::<E>() 返回真。
                //
                //
                //
                Ok(res.unwrap())
            }
            repr_data => Err(Self { repr: Repr::new(repr_data) }),
        }
    }

    /// 返回与此错误对应的 [`ErrorKind`]。
    ///
    /// 这可能是由 Rust 代码构造自定义 io::Error 设置的值，或者如果此 `io::Error` 来自操作系统，它将是从系统错误编码推断的值。
    ///
    /// 有关详细信息，请参见 [`last_os_error`]。
    ///
    /// [`last_os_error`]: Error::last_os_error
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{Error, ErrorKind};
    ///
    /// fn print_error(err: Error) {
    ///     println!("{:?}", err.kind());
    /// }
    ///
    /// fn main() {
    ///     // 由于没有发生 (visibly) 错误，这可能会打印任何内容!
    ///     // 它可能会为未识别的 (非) 错误打印一个占位符。
    ///     print_error(Error::last_os_error());
    ///     // 将打印 "AddrInUse"。
    ///     print_error(Error::new(ErrorKind::AddrInUse, "oh no!"));
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    #[inline]
    pub fn kind(&self) -> ErrorKind {
        match self.repr.data() {
            ErrorData::Os(code) => sys::decode_error_kind(code),
            ErrorData::Custom(c) => c.kind,
            ErrorData::Simple(kind) => kind,
            ErrorData::SimpleMessage(m) => m.kind,
        }
    }
}

impl fmt::Debug for Repr {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.data() {
            ErrorData::Os(code) => fmt
                .debug_struct("Os")
                .field("code", &code)
                .field("kind", &sys::decode_error_kind(code))
                .field("message", &sys::os::error_string(code))
                .finish(),
            ErrorData::Custom(c) => fmt::Debug::fmt(&c, fmt),
            ErrorData::Simple(kind) => fmt.debug_tuple("Kind").field(&kind).finish(),
            ErrorData::SimpleMessage(msg) => fmt
                .debug_struct("Error")
                .field("kind", &msg.kind)
                .field("message", &msg.message)
                .finish(),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Display for Error {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.repr.data() {
            ErrorData::Os(code) => {
                let detail = sys::os::error_string(code);
                write!(fmt, "{detail} (os error {code})")
            }
            ErrorData::Custom(ref c) => c.error.fmt(fmt),
            ErrorData::Simple(kind) => write!(fmt, "{}", kind.as_str()),
            ErrorData::SimpleMessage(msg) => msg.message.fmt(fmt),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl error::Error for Error {
    #[allow(deprecated, deprecated_in_future)]
    fn description(&self) -> &str {
        match self.repr.data() {
            ErrorData::Os(..) | ErrorData::Simple(..) => self.kind().as_str(),
            ErrorData::SimpleMessage(msg) => msg.message,
            ErrorData::Custom(c) => c.error.description(),
        }
    }

    #[allow(deprecated)]
    fn cause(&self) -> Option<&dyn error::Error> {
        match self.repr.data() {
            ErrorData::Os(..) => None,
            ErrorData::Simple(..) => None,
            ErrorData::SimpleMessage(..) => None,
            ErrorData::Custom(c) => c.error.cause(),
        }
    }

    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
        match self.repr.data() {
            ErrorData::Os(..) => None,
            ErrorData::Simple(..) => None,
            ErrorData::SimpleMessage(..) => None,
            ErrorData::Custom(c) => c.error.source(),
        }
    }
}

fn _assert_error_is_sync_send() {
    fn _is_sync_send<T: Sync + Send>() {}
    _is_sync_send::<Error>();
}