//! 文件系统操纵操作。
//!
//! 该模块包含一些操作本地文件系统内容的基本方法。
//! 该模块中的所有方法均表示跨平台文件系统操作。
//! 在 `std::os::$platform` 的扩展名 traits 中可以找到特定于平台的其他功能。
//!

#![stable(feature = "rust1", since = "1.0.0")]
#![deny(unsafe_op_in_unsafe_fn)]

#[cfg(all(test, not(any(target_os = "emscripten", target_env = "sgx"))))]
mod tests;

use crate::ffi::OsString;
use crate::fmt;
use crate::io::{self, Initializer, IoSlice, IoSliceMut, Read, Seek, SeekFrom, Write};
use crate::path::{Path, PathBuf};
use crate::sys::fs as fs_imp;
use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner};
use crate::time::SystemTime;

/// 对文件系统上打开的文件的引用。
///
/// 可以通过打开 `File` 的选项来读取或者写入 `File` 的实例。文件还实现 [`Seek`]，以更改文件内部包含的逻辑游标。
///
/// 文件离开作用域时将自动关闭。`Drop` 的实现将忽略在关闭时检测到的错误。如果必须手动处理这些错误，请使用方法 [`sync_all`]。
///
/// # Examples
///
/// 创建一个新文件并向其写入字节 (您也可以使用 [`write()`]) :
///
/// ```no_run
/// use std::fs::File;
/// use std::io::prelude::*;
///
/// fn main() -> std::io::Result<()> {
///     let mut file = File::create("foo.txt")?;
///     file.write_all(b"Hello, world!")?;
///     Ok(())
/// }
/// ```
///
/// 将文件内容读入 [`String`] (也可以使用 [`read`]) :
///
/// ```no_run
/// use std::fs::File;
/// use std::io::prelude::*;
///
/// fn main() -> std::io::Result<()> {
///     let mut file = File::open("foo.txt")?;
///     let mut contents = String::new();
///     file.read_to_string(&mut contents)?;
///     assert_eq!(contents, "Hello, world!");
///     Ok(())
/// }
/// ```
///
/// 使用缓冲的 [`Read`] 来读取文件的内容可能会更有效。这可以用 [`BufReader<R>`] 完成:
///
/// ```no_run
/// use std::fs::File;
/// use std::io::BufReader;
/// use std::io::prelude::*;
///
/// fn main() -> std::io::Result<()> {
///     let file = File::open("foo.txt")?;
///     let mut buf_reader = BufReader::new(file);
///     let mut contents = String::new();
///     buf_reader.read_to_string(&mut contents)?;
///     assert_eq!(contents, "Hello, world!");
///     Ok(())
/// }
/// ```
///
/// 请注意，尽管读写方法需要 `&mut File`，但是由于 [`Read`] 和 [`Write`] 的接口，`&File` 的持有者仍可以通过采用 `&File` 的方法或通过检索基础 OS object 并修改该文件来修改文件。办法。
///
/// 另外，许多操作系统允许通过不同的进程并发修改文件。避免假定持有 `&File` 意味着文件不会更改。
///
/// [`BufReader<R>`]: io::BufReader
/// [`sync_all`]: File::sync_all
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "File")]
pub struct File {
    inner: fs_imp::File,
}

/// 有关文件的元数据信息。
///
/// 此结构体是从 [`metadata`] 或 [`symlink_metadata`] 函数或方法返回的，表示有关文件的已知元数据，例如其权限，大小，修改时间等。
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Clone)]
pub struct Metadata(fs_imp::FileAttr);

/// 遍历目录中的条目。
///
/// 该迭代器从该模块的 [`read_dir`] 函数返回，并将产生 [`io::Result`]`<`[`DirEntry`]`>` 的实例。
/// 通过 [`DirEntry`]，可以了解类似条目路径以及可能的其他元数据的信息。
///
/// 该迭代器返回条目的顺序取决于平台和文件系统。
///
/// # Errors
///
/// 如果在迭代过程中出现某种间歇性的 IO 错误，则该 [`io::Result`] 将是 [`Err`]。
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct ReadDir(fs_imp::ReadDir);

/// [`ReadDir`] 迭代器返回的条目。
///
/// `DirEntry` 的实例表示文件系统上目录内的一个条目。
/// 可以通过方法检查每个条目，以通过全平台扩展 traits 了解完整路径或可能的其他元数据。
///
#[stable(feature = "rust1", since = "1.0.0")]
pub struct DirEntry(fs_imp::DirEntry);

/// 可用于配置文件打开方式的选项和标志。
///
/// 此构建器提供了配置 [`File`] 的打开方式以及打开的文件上允许哪些操作的功能。
/// [`File::open`] 和 [`File::create`] 方法是使用此构建器的常用选项的别名。
///
/// 一般而言，使用 `OpenOptions` 时，首先要调用 [`OpenOptions::new`]，然后链式调用方法以设置每个选项，然后调用 [`OpenOptions::open`]，传递要打开的文件的路径。
///
/// 这将为您提供一个内部带有 [`File`] 的 [`io::Result`]，您可以对其进行进一步的操作。
///
/// # Examples
///
/// 打开一个文件以读取:
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().read(true).open("foo.txt");
/// ```
///
/// 打开一个文件进行读写，如果不存在则创建一个文件:
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new()
///             .read(true)
///             .write(true)
///             .create(true)
///             .open("foo.txt");
/// ```
///
///
///
///
///
#[derive(Clone, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct OpenOptions(fs_imp::OpenOptions);

/// 表示文件上的各种权限。
///
/// 该模块当前仅提供一点信息 [`Permissions::readonly`]，该信息在所有当前支持的平台上公开。
/// 特定于 Unix 的功能 (例如模式位) 可通过 [`PermissionsExt`] trait 获得。
///
/// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt
///
///
#[derive(Clone, PartialEq, Eq, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Permissions(fs_imp::FilePermissions);

/// 表示文件类型的结构体，每个文件类型都有访问器。
/// 通过 [`Metadata::file_type`] 方法返回。
#[stable(feature = "file_type", since = "1.1.0")]
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(not(test), rustc_diagnostic_item = "FileType")]
pub struct FileType(fs_imp::FileType);

/// 用于以各种方式创建目录的构建器。
///
/// 该构建器还支持特定于平台的选项。
#[stable(feature = "dir_builder", since = "1.6.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "DirBuilder")]
#[derive(Debug)]
pub struct DirBuilder {
    inner: fs_imp::DirBuilder,
    recursive: bool,
}

/// 指示读取整个文件之前要预分配的缓冲区大小。
fn initial_buffer_size(file: &File) -> usize {
    // 分配一个额外的字节，这样就不需要在文件末尾的最后 `read` 调用之前增加缓冲区。
    // 不必担心 `usize` 溢出，因为无论那种情况，读取都会失败。
    //
    file.metadata().map(|m| m.len() as usize + 1).unwrap_or(0)
}

/// 将文件的全部内容读取为字节 vector。
///
/// 这是使用 [`File::open`] 和 [`read_to_end`] 且导入次数较少且没有中间变量的便捷函数。
/// 它会根据文件大小 (如果可用) 预分配缓冲区，因此通常比读入 [`Vec::new()`] 创建的 vector 更快。
///
///
/// [`read_to_end`]: Read::read_to_end
///
/// # Errors
///
/// 如果 `path` 还不存在，则此函数将返回错误。
/// 根据 [`OpenOptions::open`]，可能还会返回其他错误。
///
/// 如果在读取 [`io::ErrorKind::Interrupted`] 以外的其他类型的错误时遇到错误，它也会返回错误。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
/// use std::net::SocketAddr;
///
/// fn main() -> Result<(), Box<dyn std::error::Error + 'static>> {
///     let foo: SocketAddr = String::from_utf8_lossy(&fs::read("address.txt")?).parse()?;
///     Ok(())
/// }
/// ```
///
///
#[stable(feature = "fs_read_write_bytes", since = "1.26.0")]
pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {
    fn inner(path: &Path) -> io::Result<Vec<u8>> {
        let mut file = File::open(path)?;
        let mut bytes = Vec::with_capacity(initial_buffer_size(&file));
        file.read_to_end(&mut bytes)?;
        Ok(bytes)
    }
    inner(path.as_ref())
}

/// 将文件的全部内容读取为字符串。
///
/// 这是使用 [`File::open`] 和 [`read_to_string`] 且导入次数较少且没有中间变量的便捷函数。
/// 它会根据文件大小 (如果可用) 预先分配一个缓冲区，因此通常比读取用 [`String::new()`] 创建的字符串要快。
///
/// [`read_to_string`]: Read::read_to_string
///
/// # Errors
///
/// 如果 `path` 还不存在，则此函数将返回错误。
/// 根据 [`OpenOptions::open`]，可能还会返回其他错误。
///
/// 如果在读取 [`io::ErrorKind::Interrupted`] 以外的其他错误时遇到错误，或者文件的内容不是有效的 UTF-8，它也会返回错误。
///
///
/// # Examples
///
/// ```no_run
/// use std::fs;
/// use std::net::SocketAddr;
/// use std::error::Error;
///
/// fn main() -> Result<(), Box<dyn Error>> {
///     let foo: SocketAddr = fs::read_to_string("address.txt")?.parse()?;
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "fs_read_write", since = "1.26.0")]
pub fn read_to_string<P: AsRef<Path>>(path: P) -> io::Result<String> {
    fn inner(path: &Path) -> io::Result<String> {
        let mut file = File::open(path)?;
        let mut string = String::with_capacity(initial_buffer_size(&file));
        file.read_to_string(&mut string)?;
        Ok(string)
    }
    inner(path.as_ref())
}

/// 写一个切片作为文件的全部内容。
///
/// 如果该函数不存在，则此函数将创建一个文件，如果存在，则将完全替换其内容。
///
///
/// 这是使用 [`File::create`] 和 [`write_all`] 且导入次数较少的便捷函数。
///
/// [`write_all`]: Write::write_all
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::write("foo.txt", b"Lorem ipsum")?;
///     fs::write("bar.txt", "dolor sit")?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "fs_read_write_bytes", since = "1.26.0")]
pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> io::Result<()> {
    fn inner(path: &Path, contents: &[u8]) -> io::Result<()> {
        File::create(path)?.write_all(contents)
    }
    inner(path.as_ref(), contents.as_ref())
}

impl File {
    /// 尝试以只读模式打开文件。
    ///
    /// 有关更多详细信息，请参见 [`OpenOptions::open`] 方法。
    ///
    /// # Errors
    ///
    /// 如果 `path` 还不存在，则此函数将返回错误。
    /// 根据 [`OpenOptions::open`]，可能还会返回其他错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn open<P: AsRef<Path>>(path: P) -> io::Result<File> {
        OpenOptions::new().read(true).open(path.as_ref())
    }

    /// 以只写模式打开文件。
    ///
    /// 如果该函数不存在，则此函数将创建一个文件，如果存在则将截断该文件。
    ///
    ///
    /// 有关更多详细信息，请参见 [`OpenOptions::open`] 函数。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn create<P: AsRef<Path>>(path: P) -> io::Result<File> {
        OpenOptions::new().write(true).create(true).truncate(true).open(path.as_ref())
    }

    /// 返回一个新的 OpenOptions object。
    ///
    /// 如果不适合使用 `open()` 或 `create()`，则此函数返回一个新的 OpenOptions object，可用于打开或创建具有特定选项的文件。
    ///
    ///
    /// 它等效于 `OpenOptions::new()`，但允许您编写更具可读性的代码。
    /// 可以用 `File::with_options().read(true).open("foo.txt")` 代替 `OpenOptions::new().read(true).open("foo.txt")`。
    /// 这也避免了导入 `OpenOptions` 的需要。
    ///
    /// 有关更多详细信息，请参见 [`OpenOptions::new`] 函数。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// #![feature(with_options)]
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::with_options().read(true).open("foo.txt")?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[unstable(feature = "with_options", issue = "65439")]
    pub fn with_options() -> OpenOptions {
        OpenOptions::new()
    }

    /// 尝试将所有操作系统内部元数据同步到磁盘。
    ///
    /// 此函数将尝试确保所有内存数据在返回之前都已到达文件系统。
    ///
    ///
    /// 这可用于处理错误，否则这些错误仅在 `File` 关闭时才会被捕获。
    /// 丢弃文件将忽略同步此内存中数据的错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::prelude::*;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     f.write_all(b"Hello, world!")?;
    ///
    ///     f.sync_all()?;
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn sync_all(&self) -> io::Result<()> {
        self.inner.fsync()
    }

    /// 该函数与 [`sync_all`] 相似，不同之处在于它可能不会将文件元数据同步到文件系统。
    ///
    ///
    /// 这适用于必须同步内容但不需要磁盘上元数据的用例。
    /// 此方法的目标是减少磁盘操作。
    ///
    /// 请注意，某些平台可能只是根据 [`sync_all`] 来实现此目的。
    ///
    /// [`sync_all`]: File::sync_all
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::prelude::*;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     f.write_all(b"Hello, world!")?;
    ///
    ///     f.sync_data()?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn sync_data(&self) -> io::Result<()> {
        self.inner.datasync()
    }

    /// 截断或扩展基础文件，将此文件的大小更新为 `size`。
    ///
    /// 如果 `size` 小于当前文件的大小，则文件将被缩小。
    /// 如果它大于当前文件的大小，则文件将扩展到 `size`，并且所有中间数据都用 0 填充。
    ///
    ///
    /// 文件的游标未更改。
    /// 特别是，如果游标位于末尾，并且使用此操作将文件缩小了，那么游标现在将超过末尾。
    ///
    /// # Errors
    ///
    /// 如果未打开文件进行写入，则此函数将返回错误。
    /// 同样，如果期望的长度由于实现细节而导致溢出，则将返回 std::io::ErrorKind::InvalidInput。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     f.set_len(10)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 请注意，即使使用 `&self` 而不是 `&mut self`，此方法也会更改基础文件的内容。
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn set_len(&self, size: u64) -> io::Result<()> {
        self.inner.truncate(size)
    }

    /// 查询有关基础文件的元数据。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let metadata = f.metadata()?;
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn metadata(&self) -> io::Result<Metadata> {
        self.inner.file_attr().map(Metadata)
    }

    /// 创建一个新的 `File` 实例，该实例与现有 `File` 实例共享相同的基础文件句柄。
    /// 读取，写入和查找将同时影响两个 `File` 实例。
    ///
    /// # Examples
    ///
    /// 为名为 `foo.txt` 的文件创建两个句柄:
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///     let file_copy = file.try_clone()?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 假设有一个名为 `foo.txt` 的文件，其内容为 `abcdef\n`，创建两个句柄，查找其中一个，然后从另一个句柄读取剩余的字节:
    ///
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::SeekFrom;
    /// use std::io::prelude::*;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///     let mut file_copy = file.try_clone()?;
    ///
    ///     file.seek(SeekFrom::Start(3))?;
    ///
    ///     let mut contents = vec![];
    ///     file_copy.read_to_end(&mut contents)?;
    ///     assert_eq!(contents, b"def\n");
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "file_try_clone", since = "1.9.0")]
    pub fn try_clone(&self) -> io::Result<File> {
        Ok(File { inner: self.inner.duplicate()? })
    }

    /// 更改基础文件的权限。
    ///
    /// # 平台特定的行为
    ///
    /// 该函数当前对应于 Unix 上的 `fchmod` 函数和 Windows 上的 `SetFileInformationByHandle` 函数。
    ///
    /// 注意，这个 [may change in the future][changes]。
    ///
    /// [changes]: io#platform-specific-behavior
    ///
    /// # Errors
    ///
    /// 如果用户在基础文件上缺少权限更改属性，则此函数将返回错误。
    /// 在其他特定于 OS 的未指定情况下，它也可能返回错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs::File;
    ///
    ///     let file = File::open("foo.txt")?;
    ///     let mut perms = file.metadata()?.permissions();
    ///     perms.set_readonly(true);
    ///     file.set_permissions(perms)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 请注意，即使使用 `&self` 而不是 `&mut self`，此方法也会更改基础文件的权限。
    ///
    ///
    #[stable(feature = "set_permissions_atomic", since = "1.16.0")]
    pub fn set_permissions(&self, perm: Permissions) -> io::Result<()> {
        self.inner.set_permissions(perm.0)
    }
}

impl AsInner<fs_imp::File> for File {
    fn as_inner(&self) -> &fs_imp::File {
        &self.inner
    }
}
impl FromInner<fs_imp::File> for File {
    fn from_inner(f: fs_imp::File) -> File {
        File { inner: f }
    }
}
impl IntoInner<fs_imp::File> for File {
    fn into_inner(self) -> fs_imp::File {
        self.inner
    }
}

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

#[stable(feature = "rust1", since = "1.0.0")]
impl Read for File {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        self.inner.read(buf)
    }

    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
        self.inner.read_vectored(bufs)
    }

    #[inline]
    fn is_read_vectored(&self) -> bool {
        self.inner.is_read_vectored()
    }

    #[inline]
    unsafe fn initializer(&self) -> Initializer {
        // SAFETY: 保证读取可以在未初始化的内存上进行
        unsafe { Initializer::nop() }
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Write for File {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        self.inner.write(buf)
    }

    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
        self.inner.write_vectored(bufs)
    }

    #[inline]
    fn is_write_vectored(&self) -> bool {
        self.inner.is_write_vectored()
    }

    fn flush(&mut self) -> io::Result<()> {
        self.inner.flush()
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Seek for File {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.inner.seek(pos)
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Read for &File {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        self.inner.read(buf)
    }

    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
        self.inner.read_vectored(bufs)
    }

    #[inline]
    fn is_read_vectored(&self) -> bool {
        self.inner.is_read_vectored()
    }

    #[inline]
    unsafe fn initializer(&self) -> Initializer {
        // SAFETY: 保证读取可以在未初始化的内存上进行
        unsafe { Initializer::nop() }
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Write for &File {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        self.inner.write(buf)
    }

    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
        self.inner.write_vectored(bufs)
    }

    #[inline]
    fn is_write_vectored(&self) -> bool {
        self.inner.is_write_vectored()
    }

    fn flush(&mut self) -> io::Result<()> {
        self.inner.flush()
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Seek for &File {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.inner.seek(pos)
    }
}

impl OpenOptions {
    /// 创建一组可供配置的空白新选项。
    ///
    /// 所有选项最初都设置为 `false`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let mut options = OpenOptions::new();
    /// let file = options.read(true).open("foo.txt");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn new() -> Self {
        OpenOptions(fs_imp::OpenOptions::new())
    }

    /// 设置读取访问权限的选项。
    ///
    /// 该选项为 true 时，则表示打开的文件应该是可读的。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().read(true).open("foo.txt");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn read(&mut self, read: bool) -> &mut Self {
        self.0.read(read);
        self
    }

    /// 设置写访问权限的选项。
    ///
    /// 此选项为 true 时，则表示打开的文件应该是可写的。
    ///
    /// 如果该文件已经存在，则对该文件的任何写调用都将覆盖其内容，而不会将其截断。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true).open("foo.txt");
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn write(&mut self, write: bool) -> &mut Self {
        self.0.write(write);
        self
    }

    /// 设置附加模式的选项。
    ///
    /// 此选项为 true 时，表示写入将追加到文件中，而不是覆盖以前的内容。
    /// 请注意，设置 `.write(true).append(true)` 与仅设置 `.append(true)` 具有相同的效果。
    ///
    /// 对于大多数文件系统，操作系统保证所有写操作都是原子的: 不会浪费任何写操作，因为另一个进程会同时进行写操作。
    ///
    /// 使用追加模式时，可能有一个明显的注意事项: 确保一次完成将所有在一起的数据写入文件。
    /// 这可以通过在将字符串传递给 [`write()`] 之前串联字符串，或使用缓冲的 writer (具有足够大小的缓冲区) 并在消息完成后调用 [`flush()`] 来完成。
    ///
    ///
    /// 如果打开文件同时具有读取和附加访问权限，请注意在打开之后以及每次写入之后，都可以在文件末尾设置读取位置。
    /// 因此，在写入之前，请保存当前位置 (使用 [`seek`]`(`[`SeekFrom`]`::`[`Current`]`(0))`)，并在下一次读取之前将其还原。
    ///
    /// ## Note
    ///
    /// 如果该函数不存在，则该函数不会创建该文件。使用 [`OpenOptions::create`] 方法来执行此操作。
    ///
    /// [`write()`]: Write::write
    /// [`flush()`]: Write::flush
    /// [`seek`]: Seek::seek
    /// [`Current`]: SeekFrom::Current
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().append(true).open("foo.txt");
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn append(&mut self, append: bool) -> &mut Self {
        self.0.append(append);
        self
    }

    /// 设置截断上一个文件的选项。
    ///
    /// 如果使用此选项设置成功打开了文件，则如果文件已经存在，它将把文件的长度截断为 0。
    ///
    ///
    /// 该文件必须具有写访问权限才能打开，才能进行截断。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true).truncate(true).open("foo.txt");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn truncate(&mut self, truncate: bool) -> &mut Self {
        self.0.truncate(truncate);
        self
    }

    /// 设置选项以创建一个新文件，或者如果已经存在则将其打开。
    ///
    /// 为了创建文件，必须使用 [`OpenOptions::write`] 或 [`OpenOptions::append`] 访问。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true).create(true).open("foo.txt");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn create(&mut self, create: bool) -> &mut Self {
        self.0.create(create);
        self
    }

    /// 设置创建新文件的选项，如果该文件已经存在则失败。
    ///
    /// 目标位置不允许存在任何文件，(dangling) 符号链接也不允许存在。这样，如果调用成功，则保证返回的文件是新文件。
    ///
    /// 此选项很有用，因为它是原子的。
    /// 否则，在检查文件是否存在与创建新文件之间，文件可能是由另一个进程创建的 (TOCTOU 竞态条件 / 攻击)。
    ///
    ///
    /// 如果设置了 `.create_new(true)`，则忽略 [`.create()`] 和 [`.truncate()`]。
    ///
    /// 必须使用写或追加访问权限打开文件才能创建新文件。
    ///
    /// [`.create()`]: OpenOptions::create
    /// [`.truncate()`]: OpenOptions::truncate
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true)
    ///                              .create_new(true)
    ///                              .open("foo.txt");
    /// ```
    ///
    ///
    ///
    #[stable(feature = "expand_open_options2", since = "1.9.0")]
    pub fn create_new(&mut self, create_new: bool) -> &mut Self {
        self.0.create_new(create_new);
        self
    }

    /// 使用 `self` 指定的选项在 `path` 打开文件。
    ///
    /// # Errors
    ///
    /// 在许多不同的情况下，此函数将返回错误。其中列出了一些错误条件及其 [`io::ErrorKind`]。
    /// 映射到 [`io::ErrorKind`] 不是函数兼容性契约的一部分。
    ///
    /// * [`NotFound`]: 指定的文件不存在，并且没有设置 `create` 或 `create_new`。
    /// * [`NotFound`]: 文件路径的目录组件之一不存在。
    /// * [`PermissionDenied`]: 用户缺少获取文件的指定访问权限的权限。
    /// * [`PermissionDenied`]: 用户没有权限打开指定路径的目录组件之一。
    /// * [`AlreadyExists`]: 指定了 `create_new`，并且该文件已经存在。
    /// * [`InvalidInput`]: 打开选项的无效组合 (在没有写访问权，没有设置访问模式的情况下进行截断等)。
    ///
    /// 以下错误目前与任何现有的 [`io::ErrorKind`] 都不匹配:
    /// * 实际上，指定文件路径的目录组件之一不是目录。
    /// * 文件系统级错误: 已满磁盘，对只读文件系统请求的写许可权，超出磁盘配额，打开的文件过多，文件名太长，指定路径中的符号链接太多 (仅适用于 Unix 系统)，等等。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().read(true).open("foo.txt");
    /// ```
    ///
    /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists
    /// [`InvalidInput`]: io::ErrorKind::InvalidInput
    /// [`NotFound`]: io::ErrorKind::NotFound
    /// [`PermissionDenied`]: io::ErrorKind::PermissionDenied
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
        self._open(path.as_ref())
    }

    fn _open(&self, path: &Path) -> io::Result<File> {
        fs_imp::File::open(path, &self.0).map(|inner| File { inner })
    }
}

impl AsInner<fs_imp::OpenOptions> for OpenOptions {
    fn as_inner(&self) -> &fs_imp::OpenOptions {
        &self.0
    }
}

impl AsInnerMut<fs_imp::OpenOptions> for OpenOptions {
    fn as_inner_mut(&mut self) -> &mut fs_imp::OpenOptions {
        &mut self.0
    }
}

impl Metadata {
    /// 返回此元数据的文件类型。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     println!("{:?}", metadata.file_type());
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn file_type(&self) -> FileType {
        FileType(self.0.file_type())
    }

    /// 如果此元数据用于目录，则返回 `true`。
    /// 结果与 [`Metadata::is_file`] 的结果互斥，并且对于从 [`symlink_metadata`] 获得的符号链接元数据将为 false。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert!(!metadata.is_dir());
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn is_dir(&self) -> bool {
        self.file_type().is_dir()
    }

    /// 如果此元数据用于常规文件，则返回 `true`。
    /// 结果与 [`Metadata::is_dir`] 的结果互斥，并且对于从 [`symlink_metadata`] 获得的符号链接元数据将为 false。
    ///
    ///
    /// 当目标只是读取 (或写入) 源时，可以读取 (或写入) 最可靠的测试源方法是打开它。
    /// 例如，仅使用 `is_file` 才能中断类似 Unix 的系统上的工作流，例如 `diff <( prog_a )`。
    /// 有关更多信息，请参见 [`File::open`] 或 [`OpenOptions::open`]。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert!(metadata.is_file());
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn is_file(&self) -> bool {
        self.file_type().is_file()
    }

    /// 如果此元数据用于符号链接，则返回 `true`。
    ///
    /// # Examples
    ///
    #[cfg_attr(unix, doc = "```no_run")]
    #[cfg_attr(not(unix), doc = "```ignore")]
    /// #![feature(is_symlink)]
    /// use std::fs;
    /// use std::path::Path;
    /// use std::os::unix::fs::symlink;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let link_path = Path::new("link");
    ///     symlink("/origin_does_not_exists/", link_path)?;
    ///
    ///     let metadata = fs::symlink_metadata(link_path)?;
    ///
    ///     assert!(metadata.is_symlink());
    ///     Ok(())
    /// }
    /// ```
    #[unstable(feature = "is_symlink", issue = "85748")]
    pub fn is_symlink(&self) -> bool {
        self.file_type().is_symlink()
    }

    /// 返回此元数据用于的文件大小 (以字节为单位)。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert_eq!(0, metadata.len());
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn len(&self) -> u64 {
        self.0.size()
    }

    /// 返回此元数据所针对的文件的权限。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert!(!metadata.permissions().readonly());
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn permissions(&self) -> Permissions {
        Permissions(self.0.perm())
    }

    /// 返回此元数据中列出的最后修改时间。
    ///
    /// 返回的值对应于 Unix 平台上的 `stat` 的 `mtime` 字段和 Windows 平台上的 `ftLastWriteTime` 字段。
    ///
    ///
    /// # Errors
    ///
    /// 此字段可能并非在所有平台上都可用，并且会在不可用的平台上返回 `Err`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     if let Ok(time) = metadata.modified() {
    ///         println!("{:?}", time);
    ///     } else {
    ///         println!("Not supported on this platform");
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "fs_time", since = "1.10.0")]
    pub fn modified(&self) -> io::Result<SystemTime> {
        self.0.modified().map(FromInner::from_inner)
    }

    /// 返回此元数据的最后访问时间。
    ///
    /// 返回的值对应于 Unix 平台上的 `stat` 的 `atime` 字段和 Windows 平台上的 `ftLastAccessTime` 字段。
    ///
    /// 请注意，并非所有平台都会在文件的元数据中保留此字段的更新，例如，Windows 可以选择在访问文件时禁用此更新，而 Linux 同样具有 `noatime`。
    ///
    ///
    /// # Errors
    ///
    /// 此字段可能并非在所有平台上都可用，并且会在不可用的平台上返回 `Err`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     if let Ok(time) = metadata.accessed() {
    ///         println!("{:?}", time);
    ///     } else {
    ///         println!("Not supported on this platform");
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "fs_time", since = "1.10.0")]
    pub fn accessed(&self) -> io::Result<SystemTime> {
        self.0.accessed().map(FromInner::from_inner)
    }

    /// 返回此元数据中列出的创建时间。
    ///
    /// 返回的值与从 4.11 开始的 Linux 内核上的 `statx` 的 `btime` 字段，在其他 Unix 平台上的 `stat` 的 `birthtime` 字段以及在 Windows 平台上的 `ftCreationTime` 字段相对应。
    ///
    ///
    /// # Errors
    ///
    /// 此字段可能并非在所有平台上都可用，并且将在不可用的平台或文件系统上返回 `Err`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     if let Ok(time) = metadata.created() {
    ///         println!("{:?}", time);
    ///     } else {
    ///         println!("Not supported on this platform or filesystem");
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "fs_time", since = "1.10.0")]
    pub fn created(&self) -> io::Result<SystemTime> {
        self.0.created().map(FromInner::from_inner)
    }
}

#[stable(feature = "std_debug", since = "1.16.0")]
impl fmt::Debug for Metadata {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Metadata")
            .field("file_type", &self.file_type())
            .field("is_dir", &self.is_dir())
            .field("is_file", &self.is_file())
            .field("permissions", &self.permissions())
            .field("modified", &self.modified())
            .field("accessed", &self.accessed())
            .field("created", &self.created())
            .finish_non_exhaustive()
    }
}

impl AsInner<fs_imp::FileAttr> for Metadata {
    fn as_inner(&self) -> &fs_imp::FileAttr {
        &self.0
    }
}

impl FromInner<fs_imp::FileAttr> for Metadata {
    fn from_inner(attr: fs_imp::FileAttr) -> Metadata {
        Metadata(attr)
    }
}

impl Permissions {
    /// 如果这些权限描述了只读 (unwritable) 文件，则返回 `true`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     let metadata = f.metadata()?;
    ///
    ///     assert_eq!(false, metadata.permissions().readonly());
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn readonly(&self) -> bool {
        self.0.readonly()
    }

    /// 修改此权限集的只读标志。如果 `readonly` 参数是 `true`，则使用生成的 `Permission` 将更新文件权限以禁止写入。
    ///
    /// 相反，如果是 `false`，则使用生成的 `Permission` 将更新文件权限以允许写入。
    ///
    /// 此操作不修改文件系统。要修改文件系统，请使用 [`set_permissions`] 函数。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f = File::create("foo.txt")?;
    ///     let metadata = f.metadata()?;
    ///     let mut permissions = metadata.permissions();
    ///
    ///     permissions.set_readonly(true);
    ///
    ///     // 文件系统不变
    ///     assert_eq!(false, metadata.permissions().readonly());
    ///
    ///     // 只是这个特定的 `permissions`。
    ///     assert_eq!(true, permissions.readonly());
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn set_readonly(&mut self, readonly: bool) {
        self.0.set_readonly(readonly)
    }
}

impl FileType {
    /// 测试此文件类型是否代表目录。
    /// 结果与 [`is_file`] 和 [`is_symlink`] 的结果互斥; 这些测试只能通过零或其中一项。
    ///
    ///
    /// [`is_file`]: FileType::is_file
    /// [`is_symlink`]: FileType::is_symlink
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let file_type = metadata.file_type();
    ///
    ///     assert_eq!(file_type.is_dir(), false);
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn is_dir(&self) -> bool {
        self.0.is_dir()
    }

    /// 测试此文件类型是否代表常规文件。
    /// 结果与 [`is_dir`] 和 [`is_symlink`] 的结果互斥; 这些测试只能通过零或其中一项。
    ///
    /// 当目标只是读取 (或写入) 源时，可以读取 (或写入) 最可靠的测试源方法是打开它。
    /// 例如，仅使用 `is_file` 才能中断类似 Unix 的系统上的工作流，例如 `diff <( prog_a )`。
    /// 有关更多信息，请参见 [`File::open`] 或 [`OpenOptions::open`]。
    ///
    /// [`is_dir`]: FileType::is_dir
    /// [`is_symlink`]: FileType::is_symlink
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let file_type = metadata.file_type();
    ///
    ///     assert_eq!(file_type.is_file(), true);
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn is_file(&self) -> bool {
        self.0.is_file()
    }

    /// 测试此文件类型是否代表符号链接。
    /// 结果与 [`is_dir`] 和 [`is_file`] 的结果互斥; 这些测试只能通过零或其中一项。
    ///
    /// 需要使用 [`fs::symlink_metadata`] 函数而不是 [`fs::metadata`] 函数来检索基础 [`Metadata`] 结构体。
    /// [`fs::metadata`] 函数遵循符号链接，因此 [`is_symlink`] 将始终为目标文件返回 `false`。
    ///
    /// [`fs::metadata`]: metadata
    /// [`fs::symlink_metadata`]: symlink_metadata
    /// [`is_dir`]: FileType::is_dir
    /// [`is_file`]: FileType::is_file
    /// [`is_symlink`]: FileType::is_symlink
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::symlink_metadata("foo.txt")?;
    ///     let file_type = metadata.file_type();
    ///
    ///     assert_eq!(file_type.is_symlink(), false);
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn is_symlink(&self) -> bool {
        self.0.is_symlink()
    }
}

impl AsInner<fs_imp::FileType> for FileType {
    fn as_inner(&self) -> &fs_imp::FileType {
        &self.0
    }
}

impl FromInner<fs_imp::FilePermissions> for Permissions {
    fn from_inner(f: fs_imp::FilePermissions) -> Permissions {
        Permissions(f)
    }
}

impl AsInner<fs_imp::FilePermissions> for Permissions {
    fn as_inner(&self) -> &fs_imp::FilePermissions {
        &self.0
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Iterator for ReadDir {
    type Item = io::Result<DirEntry>;

    fn next(&mut self) -> Option<io::Result<DirEntry>> {
        self.0.next().map(|entry| entry.map(DirEntry))
    }
}

impl DirEntry {
    /// 返回此条目表示的文件的完整路径。
    ///
    /// 通过将 `read_dir` 的原始路径与该条目的文件名连接起来，可以创建完整路径。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     for entry in fs::read_dir(".")? {
    ///         let dir = entry?;
    ///         println!("{:?}", dir.path());
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 打印输出如下:
    ///
    /// ```text
    /// "./whatever.txt"
    /// "./foo.html"
    /// "./hello_world.rs"
    /// ```
    ///
    /// 当然，确切的文本取决于 `.` 中包含的文件。
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn path(&self) -> PathBuf {
        self.0.path()
    }

    /// 返回此条目指向的文件的元数据。
    ///
    /// 如果此函数指向符号链接，则该函数将不会遍历符号链接。要遍历符号链接，请使用 [`fs::metadata`] 或 [`fs::File::metadata`]。
    ///
    /// [`fs::metadata`]: metadata
    /// [`fs::File::metadata`]: File::metadata
    ///
    /// # 平台特定的行为
    ///
    /// 在 Windows 上，此函数的调用很便宜 (不需要额外的系统调用)，但是在 Unix 平台上，此函数等效于在路径上调用 `symlink_metadata`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs;
    ///
    /// if let Ok(entries) = fs::read_dir(".") {
    ///     for entry in entries {
    ///         if let Ok(entry) = entry {
    ///             // 在此，`entry` 是 `DirEntry`。
    ///             if let Ok(metadata) = entry.metadata() {
    ///                 // 现在，让我们显示条目的权限!
    ///                 println!("{:?}: {:?}", entry.path(), metadata.permissions());
    ///             } else {
    ///                 println!("Couldn't get metadata for {:?}", entry.path());
    ///             }
    ///         }
    ///     }
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "dir_entry_ext", since = "1.1.0")]
    pub fn metadata(&self) -> io::Result<Metadata> {
        self.0.metadata().map(Metadata)
    }

    /// 返回此条目指向的文件的文件类型。
    ///
    /// 如果此函数指向符号链接，则该函数将不会遍历符号链接。
    ///
    /// # 平台特定的行为
    ///
    /// 在 Windows 和大多数 Unix 平台上，此函数是免费的 (不需要额外的系统调用)，但是某些 Unix 平台可能需要与 `symlink_metadata` 等效的调用才能了解目标文件类型。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs;
    ///
    /// if let Ok(entries) = fs::read_dir(".") {
    ///     for entry in entries {
    ///         if let Ok(entry) = entry {
    ///             // 在此，`entry` 是 `DirEntry`。
    ///             if let Ok(file_type) = entry.file_type() {
    ///                 // 现在，让我们显示条目的文件类型!
    ///                 println!("{:?}: {:?}", entry.path(), file_type);
    ///             } else {
    ///                 println!("Couldn't get file type for {:?}", entry.path());
    ///             }
    ///         }
    ///     }
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "dir_entry_ext", since = "1.1.0")]
    pub fn file_type(&self) -> io::Result<FileType> {
        self.0.file_type().map(FileType)
    }

    /// 返回此目录条目的裸文件名，不包含任何其他前导路径组件。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs;
    ///
    /// if let Ok(entries) = fs::read_dir(".") {
    ///     for entry in entries {
    ///         if let Ok(entry) = entry {
    ///             // 在此，`entry` 是 `DirEntry`。
    ///             println!("{:?}", entry.file_name());
    ///         }
    ///     }
    /// }
    /// ```
    #[stable(feature = "dir_entry_ext", since = "1.1.0")]
    pub fn file_name(&self) -> OsString {
        self.0.file_name()
    }
}

#[stable(feature = "dir_entry_debug", since = "1.13.0")]
impl fmt::Debug for DirEntry {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("DirEntry").field(&self.path()).finish()
    }
}

impl AsInner<fs_imp::DirEntry> for DirEntry {
    fn as_inner(&self) -> &fs_imp::DirEntry {
        &self.0
    }
}

/// 从文件系统中删除文件。
///
/// 请注意，不能保证立即删除文件 (例如，取决于平台，其他打开的文件描述符可能会阻止立即删除)。
///
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `unlink` 函数和 Windows 上的 `DeleteFile` 函数。
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `path` 指向目录。
/// * 该文件不存在。
/// * 用户没有删除文件的权限。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::remove_file("a.txt")?;
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
    fs_imp::unlink(path.as_ref())
}

/// 给定路径，查询文件系统以获取有关文件，目录等的信息。
///
/// 该函数将遍历符号链接以查询有关目标文件的信息。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `stat` 函数和 Windows 上的 `GetFileAttributesEx` 函数。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * 用户没有权限在 `path` 上执行 `metadata` 调用。
/// * `path` 不存在。
///
/// # Examples
///
/// ```rust,no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let attr = fs::metadata("/some/file/path.txt")?;
///     // 检查属性...
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
    fs_imp::stat(path.as_ref()).map(Metadata)
}

/// 查询有关文件的元数据，而无需遵循符号链接。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `lstat` 函数和 Windows 上的 `GetFileAttributesEx` 函数。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * 用户没有权限在 `path` 上执行 `metadata` 调用。
/// * `path` 不存在。
///
/// # Examples
///
/// ```rust,no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let attr = fs::symlink_metadata("/some/file/path.txt")?;
///     // 检查属性...
///     Ok(())
/// }
/// ```
///
#[stable(feature = "symlink_metadata", since = "1.1.0")]
pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
    fs_imp::lstat(path.as_ref()).map(Metadata)
}

/// 将文件或目录重命名为新名称，如果 `to` 已经存在，则替换原始文件。
///
/// 如果新名称在其他安装点上，则将无法使用。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `rename` 函数和 Windows 上带有 `MOVEFILE_REPLACE_EXISTING` 标志的 `MoveFileEx` 函数。
///
/// 因此，`from` 和 `to` 都存在时的行为是不同的。在 Unix 上，如果 `from` 是目录，则 `to` 也必须是 (empty) 目录。如果 `from` 不是目录，则 `to` 也必须不是目录。
///
/// 相比之下，在 Windows 上，`from` 可以是任何东西，但是 `to` 一定不是目录。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `from` 不存在。
/// * 用户没有查看内容的权限。
/// * `from` 和 `to` 在单独的文件系统上。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::rename("a.txt", "b.txt")?; // 将 a.txt 重命名为 b.txt
///     Ok(())
/// }
/// ```
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()> {
    fs_imp::rename(from.as_ref(), to.as_ref())
}

/// 将一个文件的内容复制到另一个文件。此函数还将复制原始文件的权限位到目标文件。
///
/// 该函数将覆盖 `to` 的内容。
///
/// 请注意，如果 `from` 和 `to` 都指向同一个文件，则此操作可能会截断该文件。
///
/// 成功后，将返回复制的字节总数，该总数等于 `metadata` 报告的 `to` 文件的长度。
///
/// 如果您想将一个文件的内容复制到另一个文件，并且正在使用 [`File`]，请参见 [`io::copy()`] 函数。
///
/// # 平台特定的行为
///
/// 此函数当前与 Unix 中的 `open` 函数相对应，其中 `from` 的 `O_RDONLY` 和 `to` 的 `O_WRONLY`，`O_CREAT` 和 `O_TRUNC`。
///
/// `O_CLOEXEC` 为返回的文件描述符设置。
/// 在 Windows 上，此函数当前对应于 `CopyFileEx`。
/// 复制备用 NTFS 流，但此函数仅返回主流的大小。
/// 在 MacOS 上，此函数对应于 `fclonefileat` 和 `fcopyfile`。
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `from` 既不是普通文件，也不是普通文件的符号链接。
/// * `from` 不存在。
/// * 当前进程没有读取 `from` 或写入 `to` 的权限。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::copy("foo.txt", "bar.txt")?;  // 将 foo.txt 复制到 bar.txt
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<u64> {
    fs_imp::copy(from.as_ref(), to.as_ref())
}

/// 在文件系统上创建一个新的硬链接。
///
/// `link` 路径将是指向 `original` 路径的链接。请注意，系统通常要求这两个路径都位于同一文件系统上。
///
/// 如果 `original` 命名符号链接，则是否遵循符号链接是特定于平台的。
/// 在可能不遵循它的平台上，它不会被遵循，并且创建的硬链接指向符号链接本身。
///
/// # 平台特定的行为
///
/// 该函数目前对应于 Windows 上的 `CreateHardLink` 函数。
/// 在大多数 Unix 系统上，它对应于没有标志的 `linkat` 函数。
/// 在 Android、VxWorks 和 Redox 上，它对应于 `link` 函数。
/// 在 MacOS 上，它使用 `linkat` 函数 (如果可用)，但在 `linkat` 不可用的非常旧的系统上，`link` 在运行时被选择。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `original` 路径不是文件或不存在。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::hard_link("a.txt", "b.txt")?; // 硬链接 a.txt 到 b.txt
///     Ok(())
/// }
/// ```
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
    fs_imp::link(original.as_ref(), link.as_ref())
}

/// 在文件系统上创建一个新的符号链接。
///
/// `link` 路径将是指向 `original` 路径的符号链接。
/// 在 Windows 上，这将是文件符号链接，而不是目录符号链接。
/// 因此，应该使用平台特定的 [`std::os::unix::fs::symlink`] 和 [`std::os::windows::fs::symlink_file`] 或 [`symlink_dir`] 来明确意图。
///
///
/// [`std::os::unix::fs::symlink`]: crate::os::unix::fs::symlink
/// [`std::os::windows::fs::symlink_file`]: crate::os::windows::fs::symlink_file
/// [`symlink_dir`]: crate::os::windows::fs::symlink_dir
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::soft_link("a.txt", "b.txt")?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_deprecated(
    since = "1.1.0",
    reason = "replaced with std::os::unix::fs::symlink and \
              std::os::windows::fs::{symlink_file, symlink_dir}"
)]
pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
    fs_imp::symlink(original.as_ref(), link.as_ref())
}

/// 读取符号链接，返回链接指向的文件。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `readlink` 函数，以及 Windows 上带有 `FILE_FLAG_OPEN_REPARSE_POINT` 和 `FILE_FLAG_BACKUP_SEMANTICS` 标志的 `CreateFile` 函数。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `path` 不是符号链接。
/// * `path` 不存在。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let path = fs::read_link("a.txt")?;
///     Ok(())
/// }
/// ```
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
    fs_imp::readlink(path.as_ref())
}

/// 返回路径的规范，绝对形式，所有中间组件均已规范化且符号链接已解析。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `realpath` 函数以及 Windows 上的 `CreateFile` 和 `GetFinalPathNameByHandle` 函数。
/// 注意，这个 [may change in the future][changes]。
///
/// 在 Windows 上，这会将路径转换为使用 [扩展长度路径][path] 语法，这允许您的程序使用更长的路径名，但是意味着您只能将反斜杠分隔的路径连接到该路径，并且它可能与其他应用程序不兼容 (如果传递给该应用程序，命令行，或写入另一个应用程序可以读取的文件)。
///
///
/// [changes]: io#platform-specific-behavior
/// [path]: https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `path` 不存在。
/// * path 中的非最终组件不是目录。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let path = fs::canonicalize("../a/../foo.txt")?;
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
#[stable(feature = "fs_canonicalize", since = "1.5.0")]
pub fn canonicalize<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
    fs_imp::canonicalize(path.as_ref())
}

/// 在提供的路径中创建一个新的空目录
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `mkdir` 函数和 Windows 上的 `CreateDirectory` 函数。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// **NOTE**: 如果给定路径的父项不存在，则此函数将返回错误。
/// 要同时创建目录及其所有丢失的父目录，请使用 [`create_dir_all`] 函数。
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * 用户没有权限在 `path` 上创建目录。
/// * 给定路径的父级不存在。
/// (要同时创建目录及其所有丢失的父目录，请使用 [`create_dir_all`] 函数。)
/// * `path` 已经存在。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::create_dir("/some/dir")?;
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
    DirBuilder::new().create(path.as_ref())
}

/// 递归创建目录及其所有父组件 (如果缺少)。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `mkdir` 函数和 Windows 上的 `CreateDirectory` 函数。
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * 如果 `path` 指定的路径中的任何目录都不存在，否则无法创建。
/// [`fs::create_dir`] 概述了创建目录时 (确定目录不存在后) 的特定错误条件。
///
/// 对于在 `path` 中指定的任何目录无法同时创建的情况下，将创建一个明显的例外。
///
/// 这种情况被认为是成功的。
/// 即，保证了从多个线程或进程并发调用 `create_dir_all` 不会由于自身的竞争态而失败。
///
/// [`fs::create_dir`]: create_dir
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::create_dir_all("/some/dir")?;
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn create_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
    DirBuilder::new().recursive(true).create(path.as_ref())
}

/// 删除一个空目录。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `rmdir` 函数和 Windows 上的 `RemoveDirectory` 函数。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `path` 不存在。
/// * `path` 不是目录。
/// * 用户没有权限删除提供的 `path` 上的目录。
/// * 目录不为空。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::remove_dir("/some/dir")?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
    fs_imp::rmdir(path.as_ref())
}

/// 删除目录中的所有内容后，将在此路径中删除该目录。小心使用!
///
/// 此函数不跟随符号链接，它会简单地删除符号链接本身。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `opendir`，`lstat`，`rm` 和 `rmdir` 函数，以及 Windows 上的 `FindFirstFile`，`GetFileAttributesEx`，`DeleteFile` 和 `RemoveDirectory` 函数。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 请参见 [`fs::remove_file`] 和 [`fs::remove_dir`]。
///
/// [`fs::remove_file`]: remove_file
/// [`fs::remove_dir`]: remove_dir
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::remove_dir_all("/some/dir")?;
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
    fs_imp::remove_dir_all(path.as_ref())
}

/// 返回目录中条目的迭代器。
///
/// 迭代器将产生 [`io::Result`]`<`[`DirEntry`]`>` 的实例。
/// 最初构造迭代器后，可能会遇到新的错误。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `opendir` 函数和 Windows 上的 `FindFirstFile` 函数。
/// 推进迭代器当前对应于 Unix 上的 `readdir` 和 Windows 上的 `FindNextFile`。
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// 该迭代器返回条目的顺序取决于平台和文件系统。
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * 提供的 `path` 不存在。
/// * 该进程没有查看内容的权限。
/// * `path` 指向非目录文件。
///
/// # Examples
///
/// ```
/// use std::io;
/// use std::fs::{self, DirEntry};
/// use std::path::Path;
///
/// // 一种只访问文件的目录的可能实现
/// fn visit_dirs(dir: &Path, cb: &dyn Fn(&DirEntry)) -> io::Result<()> {
///     if dir.is_dir() {
///         for entry in fs::read_dir(dir)? {
///             let entry = entry?;
///             let path = entry.path();
///             if path.is_dir() {
///                 visit_dirs(&path, cb)?;
///             } else {
///                 cb(&entry);
///             }
///         }
///     }
///     Ok(())
/// }
/// ```
///
/// ```rust,no_run
/// use std::{fs, io};
///
/// fn main() -> io::Result<()> {
///     let mut entries = fs::read_dir(".")?
///         .map(|res| res.map(|e| e.path()))
///         .collect::<Result<Vec<_>, io::Error>>()?;
///
///     // 不保证 `read_dir` 返回条目的顺序。
///     // 如果需要可重复的排序，则应对条目进行显式排序。
///
///     entries.sort();
///
///     // 现在，条目已按其路径排序。
///
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn read_dir<P: AsRef<Path>>(path: P) -> io::Result<ReadDir> {
    fs_imp::readdir(path.as_ref()).map(ReadDir)
}

/// 更改在文件或目录上找到的权限。
///
/// # 平台特定的行为
///
/// 该函数当前对应于 Unix 上的 `chmod` 函数和 Windows 上的 `SetFileAttributes` 函数。
///
/// 注意，这个 [may change in the future][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况:
///
/// * `path` 不存在。
/// * 用户没有更改文件属性的权限。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let mut perms = fs::metadata("foo.txt")?.permissions();
///     perms.set_readonly(true);
///     fs::set_permissions("foo.txt", perms)?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "set_permissions", since = "1.1.0")]
pub fn set_permissions<P: AsRef<Path>>(path: P, perm: Permissions) -> io::Result<()> {
    fs_imp::set_perm(path.as_ref(), perm.0)
}

impl DirBuilder {
    /// 使用所有平台的默认 mode/security 设置创建一组新选项，并且这些选项也是非递归的。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs::DirBuilder;
    ///
    /// let builder = DirBuilder::new();
    /// ```
    #[stable(feature = "dir_builder", since = "1.6.0")]
    pub fn new() -> DirBuilder {
        DirBuilder { inner: fs_imp::DirBuilder::new(), recursive: false }
    }

    /// 指示应递归创建目录，并创建所有父目录。
    /// 使用相同的安全性和权限设置创建不存在的父级。
    ///
    /// 此选项默认为 `false`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs::DirBuilder;
    ///
    /// let mut builder = DirBuilder::new();
    /// builder.recursive(true);
    /// ```
    ///
    #[stable(feature = "dir_builder", since = "1.6.0")]
    pub fn recursive(&mut self, recursive: bool) -> &mut Self {
        self.recursive = recursive;
        self
    }

    /// 使用在此构建器中配置的选项来创建指定的目录。
    ///
    /// 如果目录已经存在，除非启用了递归模式，否则将被视为错误。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::{self, DirBuilder};
    ///
    /// let path = "/tmp/foo/bar/baz";
    /// DirBuilder::new()
    ///     .recursive(true)
    ///     .create(path).unwrap();
    ///
    /// assert!(fs::metadata(path).unwrap().is_dir());
    /// ```
    ///
    #[stable(feature = "dir_builder", since = "1.6.0")]
    pub fn create<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self._create(path.as_ref())
    }

    fn _create(&self, path: &Path) -> io::Result<()> {
        if self.recursive { self.create_dir_all(path) } else { self.inner.mkdir(path) }
    }

    fn create_dir_all(&self, path: &Path) -> io::Result<()> {
        if path == Path::new("") {
            return Ok(());
        }

        match self.inner.mkdir(path) {
            Ok(()) => return Ok(()),
            Err(ref e) if e.kind() == io::ErrorKind::NotFound => {}
            Err(_) if path.is_dir() => return Ok(()),
            Err(e) => return Err(e),
        }
        match path.parent() {
            Some(p) => self.create_dir_all(p)?,
            None => {
                return Err(io::Error::new_const(
                    io::ErrorKind::Uncategorized,
                    &"failed to create whole tree",
                ));
            }
        }
        match self.inner.mkdir(path) {
            Ok(()) => Ok(()),
            Err(_) if path.is_dir() => Ok(()),
            Err(e) => Err(e),
        }
    }
}

impl AsInnerMut<fs_imp::DirBuilder> for DirBuilder {
    fn as_inner_mut(&mut self) -> &mut fs_imp::DirBuilder {
        &mut self.inner
    }
}

/// 如果路径指向现有实体，则返回 `Ok(true)`。
///
/// 该函数将遍历符号链接以查询有关目标文件的信息。
/// 如果符号链接断开，则将返回 `Ok(false)`。
///
/// 与 `exists()` 方法相反，此方法不会默默地忽略与不存在的路径无关的错误。
/// (E.g.
/// 如果某些父目录的权限被拒绝，它将返回 `Err(_)`。)
///
/// # Examples
///
/// ```no_run
/// #![feature(path_try_exists)]
/// use std::fs;
///
/// assert!(!fs::try_exists("does_not_exist.txt").expect("Can't check existence of file does_not_exist.txt"));
/// assert!(fs::try_exists("/root/secret_file.txt").is_err());
/// ```
// FIXME: 稳定性应修改 `exists()` 的文档以推荐此方法。
//
#[unstable(feature = "path_try_exists", issue = "83186")]
#[inline]
pub fn try_exists<P: AsRef<Path>>(path: P) -> io::Result<bool> {
    fs_imp::try_exists(path.as_ref())
}