//! core I/O 功能的 Traits，助手和类型定义。
//!
//! `std::io` 模块包含许多在执行输入和输出时需要的常见操作。
//! 该模块中最 core 的部分是 [`Read`] 和 [`Write`] traits，它们提供用于读取和写入输入和输出的最通用接口。
//!
//! # 读和写
//!
//! 因为它们是 traits，所以 [`Read`] 和 [`Write`] 由许多其他类型实现，您也可以为您的类型实现它们。
//! 这样，您将在此模块的整个文档中看到几种不同类型的 I/O: [`File`]，[`TcpStream`]，有时甚至是 [`Vec<T>`]。
//! 例如，[`Read`] 添加了 [`read`][`Read::read`] 方法，我们可以在 [`File`] 上使用该方法:
//!
//! ```no_run
//! use std::io;
//! use std::io::prelude::*;
//! use std::fs::File;
//!
//! fn main() -> io::Result<()> {
//!     let mut f = File::open("foo.txt")?;
//!     let mut buffer = [0; 10];
//!
//!     // 最多读取 10 个字节
//!     let n = f.read(&mut buffer)?;
//!
//!     println!("The bytes: {:?}", &buffer[..n]);
//!     Ok(())
//! }
//! ```
//!
//! [`Read`] 和 [`Write`] 非常重要，两个 traits 的实现者都有一个昵称: readers 和 writers。
//! 因此，有时您会看到 `reader` 而不是 `实现 [`Read`] trait 的类型`。
//! 容易得多!
//!
//! ## Seek 和 BufRead
//!
//! 除此之外，还提供了两个重要的 traits: [`Seek`] 和 [`BufRead`]。两者都建立在 reader 的顶部，以控制读取的方式。
//! [`Seek`] 让您控制下一个字节的来源:
//!
//! ```no_run
//! use std::io;
//! use std::io::prelude::*;
//! use std::io::SeekFrom;
//! use std::fs::File;
//!
//! fn main() -> io::Result<()> {
//!     let mut f = File::open("foo.txt")?;
//!     let mut buffer = [0; 10];
//!
//!     // 跳到文件的最后 10 个字节
//!     f.seek(SeekFrom::End(-10))?;
//!
//!     // 最多读取 10 个字节
//!     let n = f.read(&mut buffer)?;
//!
//!     println!("The bytes: {:?}", &buffer[..n]);
//!     Ok(())
//! }
//! ```
//!
//! [`BufRead`] 使用内部缓冲区来提供许多其他读取方式，但是为了展示它，我们通常需要讨论缓冲区。继续阅读!
//!
//! ## BufReader 和 BufWriter
//!
//! 基于字节的接口笨拙且效率低下，因为我们需要对操作系统进行近乎恒定的调用。
//! 为了解决这个问题，`std::io` 带有两个结构体 [`BufReader`] 和 [`BufWriter`]，它们包装了 readers 和 writers。
//! 包装器使用缓冲区，从而减少了调用次数，并提供了更好的方法来访问所需的内容。
//!
//! 例如，[`BufReader`] 与 [`BufRead`] trait 一起为任何 reader 添加额外的方法:
//!
//! ```no_run
//! use std::io;
//! use std::io::prelude::*;
//! use std::io::BufReader;
//! use std::fs::File;
//!
//! fn main() -> io::Result<()> {
//!     let f = File::open("foo.txt")?;
//!     let mut reader = BufReader::new(f);
//!     let mut buffer = String::new();
//!
//!     // 将一行读入缓冲区
//!     reader.read_line(&mut buffer)?;
//!
//!     println!("{}", buffer);
//!     Ok(())
//! }
//! ```
//!
//! [`BufWriter`] 没有添加任何新的写作方式; 它只是缓冲每个调用到 [`write`][`Write::write`]:
//!
//! ```no_run
//! use std::io;
//! use std::io::prelude::*;
//! use std::io::BufWriter;
//! use std::fs::File;
//!
//! fn main() -> io::Result<()> {
//!     let f = File::create("foo.txt")?;
//!     {
//!         let mut writer = BufWriter::new(f);
//!
//!         // 向缓冲区写入一个字节
//!         writer.write(&[42])?;
//!
//!     } // writer 离开作用域后，将刷新缓冲区
//!
//!     Ok(())
//! }
//! ```
//!
//! ## 标准输入输出
//!
//! 输入的一个非常常见的来源是标准输入:
//!
//! ```no_run
//! use std::io;
//!
//! fn main() -> io::Result<()> {
//!     let mut input = String::new();
//!
//!     io::stdin().read_line(&mut input)?;
//!
//!     println!("You typed: {}", input.trim());
//!     Ok(())
//! }
//! ```
//!
//! 请注意，不能在不返回 [`Result<T, E>`][`Result`] 的函数中使用 [`?` operator]。
//! 相反，您可以在返回值上调用 [`.unwrap()`] 或 `match` 来捕获任何可能的错误:
//!
//! ```no_run
//! use std::io;
//!
//! let mut input = String::new();
//!
//! io::stdin().read_line(&mut input).unwrap();
//! ```
//!
//! 标准输出是一个非常常见的输出源:
//!
//! ```no_run
//! use std::io;
//! use std::io::prelude::*;
//!
//! fn main() -> io::Result<()> {
//!     io::stdout().write(&[42])?;
//!     Ok(())
//! }
//! ```
//!
//! 当然，直接使用 [`io::stdout`] 比使用 [`println!`] 少见。
//!
//! ## 迭代器类型
//!
//! `std::io` 提供的大量结构用于在 I/O 上进行迭代的各种方式。例如，[`Lines`] 用于拆分多行:
//!
//! ```no_run
//! use std::io;
//! use std::io::prelude::*;
//! use std::io::BufReader;
//! use std::fs::File;
//!
//! fn main() -> io::Result<()> {
//!     let f = File::open("foo.txt")?;
//!     let reader = BufReader::new(f);
//!
//!     for line in reader.lines() {
//!         println!("{}", line?);
//!     }
//!     Ok(())
//! }
//! ```
//!
//! ## Functions
//!
//! 有许多 [函数][functions-list] 提供对各种功能的访问。
//! 例如，我们可以使用以下三个函数将所有内容从标准输入复制到标准输出:
//!
//! ```no_run
//! use std::io;
//!
//! fn main() -> io::Result<()> {
//!     io::copy(&mut io::stdin(), &mut io::stdout())?;
//!     Ok(())
//! }
//! ```
//!
//! [functions-list]: #functions-1
//!
//! ## io::Result
//!
//! 最后但并非最不重要的是 [`io::Result`]。
//! 此类型用作许多 `std::io` 函数的返回类型，它们可能导致错误，也可以从您自己的函数中返回。
//! 该模块中的许多示例都使用 [`?` operator]:
//!
//! ```
//! use std::io;
//!
//! fn read_input() -> io::Result<()> {
//!     let mut input = String::new();
//!
//!     io::stdin().read_line(&mut input)?;
//!
//!     println!("You typed: {}", input.trim());
//!
//!     Ok(())
//! }
//! ```
//!
//! `read_input()` 的返回类型 [`io::Result<()>`][`io::Result`] 是函数的一种非常常见的类型，它没有 'real' 返回值，但是希望在发生错误时返回错误。
//!
//! 在这种情况下，此函数的唯一目的是读取并打印该行，因此我们使用 `()`。
//!
//! ## 平台特定的行为
//!
//! 记录了整个标准库中的许多 I/O 函数，以指示将它们委派给的各种库或 syscall。
//! 这样做是为了帮助应用程序了解幕后的情况以及调查任何可能不清楚的语义。
//! 但是请注意，这只是提供信息，而不是有约束力的契约。
//! 其中许多函数的实现会随时间而变化，并且可能调用更少或更多的 syscalls/library 函数。
//!
//! [`File`]: crate::fs::File
//! [`TcpStream`]: crate::net::TcpStream
//! [`io::stdout`]: stdout
//! [`io::Result`]: self::Result
//! [`?` operator]: ../../book/appendix-02-operators.html
//! [`Result`]: crate::result::Result
//! [`.unwrap()`]: crate::result::Result::unwrap
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

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

#[cfg(test)]
mod tests;

use crate::cmp;
use crate::convert::TryInto;
use crate::fmt;
use crate::mem::replace;
use crate::ops::{Deref, DerefMut};
use crate::ptr;
use crate::slice;
use crate::str;
use crate::sys;
use crate::sys_common::memchr;

#[stable(feature = "rust1", since = "1.0.0")]
pub use self::buffered::IntoInnerError;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::buffered::{BufReader, BufWriter, LineWriter};
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::copy::copy;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::cursor::Cursor;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::error::{Error, ErrorKind, Result};
#[unstable(feature = "internal_output_capture", issue = "none")]
#[doc(no_inline, hidden)]
pub use self::stdio::set_output_capture;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::stdio::{stderr, stdin, stdout, Stderr, Stdin, Stdout};
#[unstable(feature = "stdio_locked", issue = "86845")]
pub use self::stdio::{stderr_locked, stdin_locked, stdout_locked};
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::stdio::{StderrLock, StdinLock, StdoutLock};
#[unstable(feature = "print_internals", issue = "none")]
pub use self::stdio::{_eprint, _print};
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::util::{empty, repeat, sink, Empty, Repeat, Sink};

mod buffered;
pub(crate) mod copy;
mod cursor;
mod error;
mod impls;
pub mod prelude;
mod stdio;
mod util;

const DEFAULT_BUF_SIZE: usize = crate::sys_common::io::DEFAULT_BUF_SIZE;

pub(crate) fn cleanup() {
    stdio::cleanup()
}

struct Guard<'a> {
    buf: &'a mut Vec<u8>,
    len: usize,
}

impl Drop for Guard<'_> {
    fn drop(&mut self) {
        unsafe {
            self.buf.set_len(self.len);
        }
    }
}

// 下面的一些方法 (read_to_string，read_line) 会将数据追加到 `String` 缓冲区中，但是在执行此操作时我们需要非常小心。
// 该实现将只是调用 `.as_mut_vec()`，然后委派给一个面向字节的读取方法，但我们必须确保在返回时，切勿将 `buf` 保持在其边界内包含无效 UTF-8 的状态。
//
//
// 为此，我们使用了 RAII 保护器 (以防止 panics)，该保护器会在丢弃字符串时更新字符串的长度。
// 此保护程序最初将字符串截断为先前的长度，只有在我们确认新内容有效 UTF-8 之后，才允许它设置更长的长度。
//
// 此函数的不安全性是双重的:
//
// 1. 我们正在查看 `buf` 的原始字节，因此我们承担了 UTF-8 检查的负担。
// 2. 我们正在将原始缓冲区传递给函数 `f`，并且期望该函数仅附加字节到缓冲区。如果现有字节被覆盖以具有非 UTF-8 数据，我们将得到未定义的行为。
//
//
//
//
//
//
//
fn append_to_string<F>(buf: &mut String, f: F) -> Result<usize>
where
    F: FnOnce(&mut Vec<u8>) -> Result<usize>,
{
    unsafe {
        let mut g = Guard { len: buf.len(), buf: buf.as_mut_vec() };
        let ret = f(g.buf);
        if str::from_utf8(&g.buf[g.len..]).is_err() {
            ret.and_then(|_| {
                Err(Error::new_const(ErrorKind::InvalidData, &"stream did not contain valid UTF-8"))
            })
        } else {
            g.len = g.buf.len();
            ret
        }
    }
}

// 当填充 vector 时，它将使用自适应系统来对其进行扩展。
// 如果 reader 只有 4 个字节，而 reader 确实有大量数据要返回，那么我们要避免花大钱分配零内存。
// 如果 reader 返回的数据量非常小，则每次简单地增加 DEFAULT_BUF_SIZE 的额外空间就比默认保留大小 32 慢 X4X 的 4,500 倍。
//
//
// 因为我们正在使用未初始化的数据扩展受信任 readers 的缓冲区，所以我们需要确保截断该 panics 中的任何一个。
//
//
//
fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize> {
    read_to_end_with_reservation(r, buf, |_| 32)
}

fn read_to_end_with_reservation<R, F>(
    r: &mut R,
    buf: &mut Vec<u8>,
    mut reservation_size: F,
) -> Result<usize>
where
    R: Read + ?Sized,
    F: FnMut(&R) -> usize,
{
    let start_len = buf.len();
    let mut g = Guard { len: buf.len(), buf };
    loop {
        if g.len == g.buf.len() {
            unsafe {
                // FIXME(danielhenrymantilla): #42788
                //
                //   - 这将创建 (mut) 对 _uninitialized_ 整数切片的引用，这是 **未定义的行为**
                //
                //   - 基于标准库对不稳定 rustc 内部的权限知识，只有标准库才能做到这一点。
                //
                //
                //
                g.buf.reserve(reservation_size(r));
                let capacity = g.buf.capacity();
                g.buf.set_len(capacity);
                r.initializer().initialize(&mut g.buf[g.len..]);
            }
        }

        let buf = &mut g.buf[g.len..];
        match r.read(buf) {
            Ok(0) => return Ok(g.len - start_len),
            Ok(n) => {
                // 我们不允许读取伪造的值。
                // 如果太大，则返回的 vec 的长度可能会超出其容量，或者如果溢出，则会缩短 vec，如果通过 read_to_string 调用，则会创建无效的字符串。
                //
                assert!(n <= buf.len());
                g.len += n;
            }
            Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
            Err(e) => return Err(e),
        }
    }
}

pub(crate) fn default_read_vectored<F>(read: F, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>
where
    F: FnOnce(&mut [u8]) -> Result<usize>,
{
    let buf = bufs.iter_mut().find(|b| !b.is_empty()).map_or(&mut [][..], |b| &mut **b);
    read(buf)
}

pub(crate) fn default_write_vectored<F>(write: F, bufs: &[IoSlice<'_>]) -> Result<usize>
where
    F: FnOnce(&[u8]) -> Result<usize>,
{
    let buf = bufs.iter().find(|b| !b.is_empty()).map_or(&[][..], |b| &**b);
    write(buf)
}

pub(crate) fn default_read_exact<R: Read + ?Sized>(this: &mut R, mut buf: &mut [u8]) -> Result<()> {
    while !buf.is_empty() {
        match this.read(buf) {
            Ok(0) => break,
            Ok(n) => {
                let tmp = buf;
                buf = &mut tmp[n..];
            }
            Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
            Err(e) => return Err(e),
        }
    }
    if !buf.is_empty() {
        Err(Error::new_const(ErrorKind::UnexpectedEof, &"failed to fill whole buffer"))
    } else {
        Ok(())
    }
}

/// `Read` trait 允许从源读取字节。
///
/// `Read` trait 的实现者称为 'readers'。
///
/// Readers 由一种必需的方法 [`read()`] 定义。对 [`read()`] 的每次调用都会尝试将字节从此源拉入提供的缓冲区。
/// [`read()`] 还实现了许多其他方法，从而为实现者提供了多种读取字节的方式，而只需要实现一种方法即可。
///
/// Readers 旨在彼此组成。[`std::io`] 上的许多实现器都采用并提供实现 `Read` trait 的类型。
///
/// 请注意，对 [`read()`] 的每次调用都可能涉及一个系统调用，因此，使用实现 [`BufRead`] 的东西 (例如 [`BufReader`]) 会更加有效。
///
///
/// # Examples
///
/// [`File`] 的工具 `Read`:
///
/// ```no_run
/// use std::io;
/// use std::io::prelude::*;
/// use std::fs::File;
///
/// fn main() -> io::Result<()> {
///     let mut f = File::open("foo.txt")?;
///     let mut buffer = [0; 10];
///
///     // 最多读取 10 个字节
///     f.read(&mut buffer)?;
///
///     let mut buffer = Vec::new();
///     // 读取整个文件
///     f.read_to_end(&mut buffer)?;
///
///     // 读入一个字符串，这样就不需要进行转换。
///     let mut buffer = String::new();
///     f.read_to_string(&mut buffer)?;
///
///     // 和更多! 有关更多详细信息，请参见其他方法。
///     Ok(())
/// }
/// ```
///
/// 从 [`&str`] 读取，因为 [`&[u8]`][prim@slice] 实现了 `Read`:
///
/// ```no_run
/// # use std::io;
/// use std::io::prelude::*;
///
/// fn main() -> io::Result<()> {
///     let mut b = "This string will be read".as_bytes();
///     let mut buffer = [0; 10];
///
///     // 最多读取 10 个字节
///     b.read(&mut buffer)?;
///
///     // 等等... 它的工作原理与文件一样!
///     Ok(())
/// }
/// ```
///
/// [`read()`]: Read::read
/// [`&str`]: prim@str
/// [`std::io`]: self
/// [`File`]: crate::fs::File
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(notable_trait)]
#[cfg_attr(not(test), rustc_diagnostic_item = "IoRead")]
pub trait Read {
    /// 从该源中提取一些字节到指定的缓冲区中，返回读取的字节数。
    ///
    /// 该函数不提供有关是否阻塞等待数据的任何保证，但是如果 object 需要阻塞读取而不能阻塞，则通常会通过 [`Err`] 返回值来发出信号。
    ///
    ///
    /// 如果此方法的返回值为 [`Ok(n)`]，则实现必须保证 `0 <= n <= buf.len()`。
    /// `n` 值非零表示缓冲区 `buf` 已填充有来自该源的 `n` 字节的数据。
    /// 如果 `n` 是 `0`，则它可以指示以下两种情况之一:
    ///
    /// 1. reader 已到达其 "end of file"，可能不再能够产生字节。请注意，这并不意味着 reader 总是会不再能够生成字节。
    /// 例如，在 Linux 上，此方法将调用 [`TcpStream`] 的 `recv` 系统调用，其中返回零表示连接已正确关闭。
    /// 而对于 [`File`]，有可能到达文件末尾并得到零结果，但如果将更多数据附加到文件中，future 对 `read` 的调用将返回更多数据。
    /// 2. 指定的缓冲区的长度为 0 个字节。
    ///
    /// 如果返回值 `n` 小于缓冲区大小，即使 reader 不在流的末尾，也不会出错。
    /// 例如，这可能是因为现在实际可用的字节较少 (例如，接近文件末尾) 或 read() 被信号中断。
    ///
    /// 由于此 trait 可以安全实现，因此调用者不能依靠 `n <= buf.len()` 来保证安全。
    /// 当使用 `unsafe` 函数访问读取的字节时，需要格外小心。
    /// 调用者必须确保即使 `n > buf.len()` 也不能进行未经检查的越界访问。
    ///
    /// 调用此函数时，不能保证 `buf` 的内容，实现不能依赖 `buf` 内容的任何属性为 true。
    /// 建议 `implementations` 仅将数据写入 `buf`，而不要读取其内容。
    ///
    /// 但是，相应地，此方法的 *调用者* 不能对实现如何使用 `buf` 做出任何保证。
    /// trait 可以安全地实现，因此应该写到缓冲区的代码也可能会从中读取。
    /// 您有责任在调用 `read` 之前确保 `buf` 已初始化。
    /// 用未初始化的 `buf` (通过 [`MaybeUninit<T>`] 获得的那种) 来调用 `read` 是不安全的，并且可能导致未定义的行为。
    ///
    /// [`MaybeUninit<T>`]: crate::mem::MaybeUninit
    ///
    /// # Errors
    ///
    /// 如果此函数遇到任何形式的 I/O 或其他错误，将返回一个错误成员。如果返回错误，则必须保证未读取任何字节。
    ///
    /// [`ErrorKind::Interrupted`] 类型的错误是非致命错误，如果没有其他事情可做，则应重试读取操作。
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`Ok(n)`]: Ok
    /// [`File`]: crate::fs::File
    /// [`TcpStream`]: crate::net::TcpStream
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let mut buffer = [0; 10];
    ///
    ///     // 最多读取 10 个字节
    ///     let n = f.read(&mut buffer[..])?;
    ///
    ///     println!("The bytes: {:?}", &buffer[..n]);
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn read(&mut self, buf: &mut [u8]) -> Result<usize>;

    /// 与 `read` 相似，不同之处在于它读入缓冲区的一部分。
    ///
    /// 复制数据以按顺序填充每个缓冲区，而写入的最终缓冲区可能仅被部分填充。
    /// 此方法必须等效于使用级联缓冲区对 `read` 的单个调用。
    ///
    /// 默认实现使用提供的第一个非空缓冲区调用 `read`，如果不存在，则为空。
    ///
    ///
    ///
    #[stable(feature = "iovec", since = "1.36.0")]
    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize> {
        default_read_vectored(|b| self.read(b), bufs)
    }

    /// 确定此 `Read` 是否具有有效的 `read_vectored` 实现。
    ///
    /// 如果 `Read` 没有覆盖默认的 `read_vectored` 实现，则使用它的代码可能希望完全避免使用该方法，并合并写入单个缓冲区以提高性能。
    ///
    ///
    /// 默认实现返回 `false`。
    ///
    ///
    #[unstable(feature = "can_vector", issue = "69941")]
    fn is_read_vectored(&self) -> bool {
        false
    }

    /// 确定该 `Reader` 是否可以与未初始化内存的缓冲区一起使用。
    ///
    /// 默认实现返回一个初始化，它将零个缓冲区。
    ///
    /// 如果 `Reader' 保证它可以与未初始化的内存一起正常工作，则应调用 [`Initializer::nop()`]。
    /// 有关详细信息，请参见 [`Initializer`] 的文档。
    ///
    /// 该方法的行为必须独立于 `Reader` 的状态 - 该方法仅使用 `&self`，以便可以通过 trait 对象使用它。
    ///
    ///
    /// # Safety
    ///
    /// 这种方法是不安全的，因为 `Read` 可能会从另一个没有 `unsafe` 块的 `Read` 类型返回非归零的 `Initializer`。
    ///
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "read_initializer", issue = "42788")]
    #[inline]
    unsafe fn initializer(&self) -> Initializer {
        Initializer::zeroing()
    }

    /// 读取所有字节，直到此源中的 EOF 为止，然后将它们放入 `buf`。
    ///
    /// 从该源读取的所有字节都将附加到指定的缓冲区 `buf`。
    /// 该函数将不断调用 [`read()`] 来向 `buf` 附加更多数据，直到 [`read()`] 返回 [`Ok(0)`] 或非 [`ErrorKind::Interrupted`] 类型的错误为止。
    ///
    ///
    /// 如果成功，此函数将返回读取的字节总数。
    ///
    /// # Errors
    ///
    /// 如果此函数遇到 [`ErrorKind::Interrupted`] 类型的错误，则该错误将被忽略，并且操作将继续。
    ///
    /// 如果遇到任何其他读取错误，则此函数立即返回。任何已读取的字节将被附加到 `buf`。
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`read()`]: Read::read
    /// [`Ok(0)`]: Ok
    /// [`File`]: crate::fs::File
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let mut buffer = Vec::new();
    ///
    ///     // 读取整个文件
    ///     f.read_to_end(&mut buffer)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// (有关读取文件的信息，另请参见 [`std::fs::read`] 便利函数。)
    ///
    /// [`std::fs::read`]: crate::fs::read
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
        read_to_end(self, buf)
    }

    /// 读取所有字节，直到该源中的 EOF 为止，然后将它们附加到 `buf`。
    ///
    /// 如果成功，则此函数返回已读取并附加到 `buf` 的字节数。
    ///
    /// # Errors
    ///
    /// 如果此流中的数据 *不是* 有效的 UTF-8，则返回错误，并且 `buf` 不变。
    ///
    ///
    /// 有关其他错误语义，请参见 [`read_to_end`]。
    ///
    /// [`read_to_end`]: Read::read_to_end
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`File`]: crate::fs::File
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let mut buffer = String::new();
    ///
    ///     f.read_to_string(&mut buffer)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// (有关读取文件的信息，另请参见 [`std::fs::read_to_string`] 便利函数。)
    ///
    /// [`std::fs::read_to_string`]: crate::fs::read_to_string
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn read_to_string(&mut self, buf: &mut String) -> Result<usize> {
        // 请注意，我们在这里 *不* 调用 `.read_to_end()`。我们将 `&mut Vec<u8>` (`buf` 的原始内容) 传递给 `read_to_end` 方法以填充它。
        // 任意实现都可以覆盖 vector 的全部内容，而不仅仅是追加到 vector (这是我们所期望的)。
        //
        // 为了避免不必要地检查整个缓冲区的 UTF-8 大小，我们将其传递给我们的硬编码 `read_to_end` 实现，我们知道可以保证只将数据读入缓冲区的末尾。
        //
        //
        //
        //
        //
        append_to_string(buf, |b| read_to_end(self, b))
    }

    /// 读取填充 `buf` 所需的确切字节数。
    ///
    /// 该函数读取所需的字节数以完全填充指定的缓冲区 `buf`。
    ///
    /// 调用此函数时，不能保证 `buf` 的内容，实现不能依赖 `buf` 内容的任何属性为 true。
    /// 建议实现仅将数据写入 `buf`，而不读取其内容。
    /// [`read`] 上的文档对此主题有更详细的说明。
    ///
    /// # Errors
    ///
    /// 如果此函数遇到 [`ErrorKind::Interrupted`] 类型的错误，则该错误将被忽略，并且操作将继续。
    ///
    /// 如果此函数在完全填充缓冲区之前遇到 "end of file"，它将返回 [`ErrorKind::UnexpectedEof`] 类型的错误。
    /// 在这种情况下，`buf` 的内容未指定。
    ///
    /// 如果遇到任何其他读取错误，则此函数立即返回。在这种情况下，`buf` 的内容未指定。
    ///
    /// 如果此函数返回错误，则无法确定已读取多少字节，但读取的字节数永远不会超过完全填充缓冲区所需的字节数。
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`read`]: Read::read
    /// [`File`]: crate::fs::File
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let mut buffer = [0; 10];
    ///
    ///     // 精确读取 10 个字节
    ///     f.read_exact(&mut buffer)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "read_exact", since = "1.6.0")]
    fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
        default_read_exact(self, buf)
    }

    /// 为此 `Read` 实例创建 "by reference" 适配器。
    ///
    /// 返回的适配器还实现了 `Read`，并将仅借用此当前的 reader。
    ///
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`File`]: crate::fs::File
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::Read;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let mut buffer = Vec::new();
    ///     let mut other_buffer = Vec::new();
    ///
    ///     {
    ///         let reference = f.by_ref();
    ///
    ///         // 最多读取 5 个字节
    ///         reference.take(5).read_to_end(&mut buffer)?;
    ///
    ///     } // 丢弃 &mut 引用，以便我们可以再次使用 f
    ///
    ///     // 原始文件仍然可用，请读取其余内容
    ///     f.read_to_end(&mut other_buffer)?;
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn by_ref(&mut self) -> &mut Self
    where
        Self: Sized,
    {
        self
    }

    /// 将此 `Read` 实例的字节数转换为 [`Iterator`]。
    ///
    /// 返回的类型实现 [`Iterator`]，其中 `Item` 为 [`Result`]`<`[`u8`]`， `[`io::Error`]`>`.
    ///
    /// 如果成功读取了一个字节，则产生的项为 [`Ok`]，否则为 [`Err`]。
    /// EOF 映射为从此迭代器返回 [`None`]。
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`File`]: crate::fs::File
    /// [`Result`]: crate::result::Result
    /// [`io::Error`]: self::Error
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///
    ///     for byte in f.bytes() {
    ///         println!("{}", byte.unwrap());
    ///     }
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn bytes(self) -> Bytes<Self>
    where
        Self: Sized,
    {
        Bytes { inner: self }
    }

    /// 创建一个适配器，它将将此流与另一个流链接。
    ///
    /// 返回的 `Read` 实例将首先从该 object 读取所有字节，直到遇到 EOF。
    /// 之后，输出等同于 `next` 的输出。
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`File`]: crate::fs::File
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f1 = File::open("foo.txt")?;
    ///     let mut f2 = File::open("bar.txt")?;
    ///
    ///     let mut handle = f1.chain(f2);
    ///     let mut buffer = String::new();
    ///
    ///     // 将值读入字符串。
    ///     // 我们可以在这里使用任何 Read 方法，这只是一个示例。
    ///     handle.read_to_string(&mut buffer)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn chain<R: Read>(self, next: R) -> Chain<Self, R>
    where
        Self: Sized,
    {
        Chain { first: self, second: next, done_first: false }
    }

    /// 创建一个适配器，该适配器最多可以从中读取 `limit` 字节。
    ///
    /// 此函数返回 `Read` 的新实例，该实例最多读取 `limit` 字节，此后它将始终返回 EOF ([`Ok(0)`])。
    /// 任何读取错误都不会计入读取的字节数，并且 [`read()`] 的 future 调用可能会成功。
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`:
    ///
    /// [`File`]: crate::fs::File
    /// [`Ok(0)`]: Ok
    /// [`read()`]: Read::read
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let mut buffer = [0; 5];
    ///
    ///     // 最多读取五个字节
    ///     let mut handle = f.take(5);
    ///
    ///     handle.read(&mut buffer)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn take(self, limit: u64) -> Take<Self>
    where
        Self: Sized,
    {
        Take { inner: self, limit }
    }
}

/// 将 [reader][Read] 的所有字节读入新的 [`String`]。
///
/// 这是 [`Read::read_to_string`] 的便捷函数。
/// 使用此函数避免了必须先创建变量，并且提供了更多的类型安全性，因为只有在没有错误的情况下才可以取出缓冲区。
/// (如果使用 [`Read::read_to_string`]，则必须记住检查读取是否成功，否则缓冲区将为空或仅部分充满。)
///
///
/// # Performance
///
/// 该函数提高了易用性和类型安全性的缺点是，它使您对性能的控制较少。
/// 例如，您不能像使用 [`String::with_capacity`] 和 [`Read::read_to_string`] 一样预先分配内存。
/// 另外，如果读取时发生错误，则无法重新使用缓冲区。
///
/// 在许多情况下，此函数的性能将是适当的，并且易于使用和类型安全性的折衷是值得的。
/// 但是，在某些情况下，您需要对性能进行更多控制，在这些情况下，您绝对应该直接使用 [`Read::read_to_string`]。
///
/// # Errors
///
/// 此函数迫使您处理错误，因为输出 (`String`) 包装在 [`Result`] 中。
/// 有关可能发生的错误，请参见 [`Read::read_to_string`]。
/// 如果发生任何错误，您将得到 [`Err`]，因此您不必担心缓冲区为空或部分已满。
///
/// # Examples
///
/// ```no_run
/// #![feature(io_read_to_string)]
///
/// # use std::io;
/// fn main() -> io::Result<()> {
///     let stdin = io::read_to_string(&mut io::stdin())?;
///     println!("Stdin was:");
///     println!("{}", stdin);
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
#[unstable(feature = "io_read_to_string", issue = "80218")]
pub fn read_to_string<R: Read>(reader: &mut R) -> Result<String> {
    let mut buf = String::new();
    reader.read_to_string(&mut buf)?;
    Ok(buf)
}

/// `Read::read_vectored` 使用的缓冲区类型。
///
/// 从语义上来说，它是 `&mut [u8]` 的包装，但是可以保证与 Unix 平台上的 `iovec` 类型和 Windows 上的 `WSABUF` 具有 ABI 兼容性。
///
///
#[stable(feature = "iovec", since = "1.36.0")]
#[repr(transparent)]
pub struct IoSliceMut<'a>(sys::io::IoSliceMut<'a>);

#[stable(feature = "iovec-send-sync", since = "1.44.0")]
unsafe impl<'a> Send for IoSliceMut<'a> {}

#[stable(feature = "iovec-send-sync", since = "1.44.0")]
unsafe impl<'a> Sync for IoSliceMut<'a> {}

#[stable(feature = "iovec", since = "1.36.0")]
impl<'a> fmt::Debug for IoSliceMut<'a> {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(self.0.as_slice(), fmt)
    }
}

impl<'a> IoSliceMut<'a> {
    /// 创建一个新的 `IoSliceMut`，包装一个字节切片。
    ///
    /// # Panics
    ///
    /// 如果切片大于 4GB，则在 Windows 上使用 Panics。
    #[stable(feature = "iovec", since = "1.36.0")]
    #[inline]
    pub fn new(buf: &'a mut [u8]) -> IoSliceMut<'a> {
        IoSliceMut(sys::io::IoSliceMut::new(buf))
    }

    /// 前进切片的内部游标。
    ///
    /// 另请参见 [`IoSliceMut::advance_slices`] 以推进多个缓冲区的游标。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(io_slice_advance)]
    ///
    /// use std::io::IoSliceMut;
    /// use std::ops::Deref;
    ///
    /// let mut data = [1; 8];
    /// let mut buf = IoSliceMut::new(&mut data);
    ///
    /// // 将 3 个字节标记为已读。
    /// buf.advance(3);
    /// assert_eq!(buf.deref(), [1; 5].as_ref());
    /// ```
    #[unstable(feature = "io_slice_advance", issue = "62726")]
    #[inline]
    pub fn advance(&mut self, n: usize) {
        self.0.advance(n)
    }

    /// 前进切片的内部游标。
    ///
    /// # Notes
    ///
    /// 如果游标没有移到切片的末尾，则可以修改切片中的元素。
    /// 例如，如果我们有一个带有 2 个 `IoSliceMut` 的缓冲区切片，两个缓冲区的长度均为 8，并且我们将游标前进了 10 个字节，则第一个 `IoSliceMut` 将保持不变，但是第二个 `IoSliceMut` 将被修改以删除前 2 个字节 (10-8)。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(io_slice_advance)]
    ///
    /// use std::io::IoSliceMut;
    /// use std::ops::Deref;
    ///
    /// let mut buf1 = [1; 8];
    /// let mut buf2 = [2; 16];
    /// let mut buf3 = [3; 8];
    /// let mut bufs = &mut [
    ///     IoSliceMut::new(&mut buf1),
    ///     IoSliceMut::new(&mut buf2),
    ///     IoSliceMut::new(&mut buf3),
    /// ][..];
    ///
    /// // 将 10 个字节标记为已读。
    /// IoSliceMut::advance_slices(&mut bufs, 10);
    /// assert_eq!(bufs[0].deref(), [2; 14].as_ref());
    /// assert_eq!(bufs[1].deref(), [3; 8].as_ref());
    /// ```
    ///
    ///
    #[unstable(feature = "io_slice_advance", issue = "62726")]
    #[inline]
    pub fn advance_slices(bufs: &mut &mut [IoSliceMut<'a>], n: usize) {
        // 要删除的缓冲区数。
        let mut remove = 0;
        // 所有要删除的缓冲区的总长度。
        let mut accumulated_len = 0;
        for buf in bufs.iter() {
            if accumulated_len + buf.len() > n {
                break;
            } else {
                accumulated_len += buf.len();
                remove += 1;
            }
        }

        *bufs = &mut replace(bufs, &mut [])[remove..];
        if !bufs.is_empty() {
            bufs[0].advance(n - accumulated_len)
        }
    }
}

#[stable(feature = "iovec", since = "1.36.0")]
impl<'a> Deref for IoSliceMut<'a> {
    type Target = [u8];

    #[inline]
    fn deref(&self) -> &[u8] {
        self.0.as_slice()
    }
}

#[stable(feature = "iovec", since = "1.36.0")]
impl<'a> DerefMut for IoSliceMut<'a> {
    #[inline]
    fn deref_mut(&mut self) -> &mut [u8] {
        self.0.as_mut_slice()
    }
}

/// `Write::write_vectored` 使用的缓冲区类型。
///
/// 从语义上来说，它是 `&[u8]` 的包装，但是可以保证与 Unix 平台上的 `iovec` 类型和 Windows 上的 `WSABUF` 具有 ABI 兼容性。
///
///
#[stable(feature = "iovec", since = "1.36.0")]
#[derive(Copy, Clone)]
#[repr(transparent)]
pub struct IoSlice<'a>(sys::io::IoSlice<'a>);

#[stable(feature = "iovec-send-sync", since = "1.44.0")]
unsafe impl<'a> Send for IoSlice<'a> {}

#[stable(feature = "iovec-send-sync", since = "1.44.0")]
unsafe impl<'a> Sync for IoSlice<'a> {}

#[stable(feature = "iovec", since = "1.36.0")]
impl<'a> fmt::Debug for IoSlice<'a> {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(self.0.as_slice(), fmt)
    }
}

impl<'a> IoSlice<'a> {
    /// 创建一个新的 `IoSlice`，包装一个字节切片。
    ///
    /// # Panics
    ///
    /// 如果切片大于 4GB，则在 Windows 上使用 Panics。
    #[stable(feature = "iovec", since = "1.36.0")]
    #[inline]
    pub fn new(buf: &'a [u8]) -> IoSlice<'a> {
        IoSlice(sys::io::IoSlice::new(buf))
    }

    /// 前进切片的内部游标。
    ///
    /// 另请参见 [`IoSlice::advance_slices`] 以推进多个缓冲区的游标。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(io_slice_advance)]
    ///
    /// use std::io::IoSlice;
    /// use std::ops::Deref;
    ///
    /// let mut data = [1; 8];
    /// let mut buf = IoSlice::new(&mut data);
    ///
    /// // 将 3 个字节标记为已读。
    /// buf.advance(3);
    /// assert_eq!(buf.deref(), [1; 5].as_ref());
    /// ```
    #[unstable(feature = "io_slice_advance", issue = "62726")]
    #[inline]
    pub fn advance(&mut self, n: usize) {
        self.0.advance(n)
    }

    /// 前进切片的内部游标。
    ///
    /// # Notes
    ///
    /// 如果游标没有移到切片的末尾，则可以修改切片中的元素。
    /// 例如，如果我们有一个缓冲区切片，缓冲区的长度均为 2`IoSlice'，长度均为 8，并且将游标向前移动了 10 个字节，则第一个 `IoSlice` 将保持不变，但是第二个 `IoSlice` 将被修改以删除前两个字节 (10-8)。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(io_slice_advance)]
    ///
    /// use std::io::IoSlice;
    /// use std::ops::Deref;
    ///
    /// let buf1 = [1; 8];
    /// let buf2 = [2; 16];
    /// let buf3 = [3; 8];
    /// let mut bufs = &mut [
    ///     IoSlice::new(&buf1),
    ///     IoSlice::new(&buf2),
    ///     IoSlice::new(&buf3),
    /// ][..];
    ///
    /// // 将 10 个字节标记为已写入。
    /// IoSlice::advance_slices(&mut bufs, 10);
    /// assert_eq!(bufs[0].deref(), [2; 14].as_ref());
    /// assert_eq!(bufs[1].deref(), [3; 8].as_ref());
    ///
    ///
    #[unstable(feature = "io_slice_advance", issue = "62726")]
    #[inline]
    pub fn advance_slices(bufs: &mut &mut [IoSlice<'a>], n: usize) {
        // 要删除的缓冲区数。
        let mut remove = 0;
        // 所有要删除的缓冲区的总长度。
        let mut accumulated_len = 0;
        for buf in bufs.iter() {
            if accumulated_len + buf.len() > n {
                break;
            } else {
                accumulated_len += buf.len();
                remove += 1;
            }
        }

        *bufs = &mut replace(bufs, &mut [])[remove..];
        if !bufs.is_empty() {
            bufs[0].advance(n - accumulated_len)
        }
    }
}

#[stable(feature = "iovec", since = "1.36.0")]
impl<'a> Deref for IoSlice<'a> {
    type Target = [u8];

    #[inline]
    fn deref(&self) -> &[u8] {
        self.0.as_slice()
    }
}

/// 一种类型，用于有条件地初始化传递给 `Read` 方法的缓冲区。
#[unstable(feature = "read_initializer", issue = "42788")]
#[derive(Debug)]
pub struct Initializer(bool);

impl Initializer {
    /// 返回一个新的 `Initializer`，它将缓冲区归零。
    #[unstable(feature = "read_initializer", issue = "42788")]
    #[inline]
    pub fn zeroing() -> Initializer {
        Initializer(true)
    }

    /// 返回不会将缓冲区归零的新 `Initializer`。
    ///
    /// # Safety
    ///
    /// 这只能由 `Read` 调用，该 `Read` 保证它们不会从传递给 `Read` 方法的缓冲区中读取，并且该方法的返回值准确地反映了已写入缓冲区头部的字节数。
    ///
    ///
    ///
    #[unstable(feature = "read_initializer", issue = "42788")]
    #[inline]
    pub unsafe fn nop() -> Initializer {
        Initializer(false)
    }

    /// 指示是否应初始化缓冲区。
    #[unstable(feature = "read_initializer", issue = "42788")]
    #[inline]
    pub fn should_initialize(&self) -> bool {
        self.0
    }

    /// 必要时初始化缓冲区。
    #[unstable(feature = "read_initializer", issue = "42788")]
    #[inline]
    pub fn initialize(&self, buf: &mut [u8]) {
        if self.should_initialize() {
            unsafe { ptr::write_bytes(buf.as_mut_ptr(), 0, buf.len()) }
        }
    }
}

/// trait 用于面向字节的 sinks 的对象。
///
/// `Write` trait 的实现者有时称为 'writers'。
///
/// Writers 由两种必需的方法 [`write`] 和 [`flush`] 定义:
///
/// * [`write`] 方法将尝试将一些数据写入 object，返回成功写入的字节数。
///
/// * [`flush`] 方法对于适配器和显式缓冲区本身很有用，以确保所有缓冲数据都已推送到 `true sink`。
///
///
/// Writers 旨在彼此组成。
/// [`std::io`] 上的许多实现器都采用并提供实现 `Write` trait 的类型。
///
/// [`write`]: Write::write
/// [`flush`]: Write::flush
/// [`std::io`]: self
///
/// # Examples
///
/// ```no_run
/// use std::io::prelude::*;
/// use std::fs::File;
///
/// fn main() -> std::io::Result<()> {
///     let data = b"some bytes";
///
///     let mut pos = 0;
///     let mut buffer = File::create("foo.txt")?;
///
///     while pos < data.len() {
///         let bytes_written = buffer.write(&data[pos..])?;
///         pos += bytes_written;
///     }
///     Ok(())
/// }
/// ```
///
/// trait 还提供了便捷的方法，例如 [`write_all`]，它在循环中调用 `write`，直到其整个输入被写入为止。
///
/// [`write_all`]: Write::write_all
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(notable_trait)]
#[cfg_attr(not(test), rustc_diagnostic_item = "IoWrite")]
pub trait Write {
    /// 在此 writer 中写入一个缓冲区，返回写入的字节数。
    ///
    /// 该函数将尝试写入 `buf` 的全部内容，但是整个写入可能不会成功，或者该写入也可能会产生错误。
    /// 对 `write` 的调用表示 *at most 对任何包装的 object 进行写操作的尝试。
    ///
    /// 不能保证对 `write` 的调用会阻塞等待数据写入的等待，否则可以通过 [`Err`] 成员指示将阻塞的写入。
    ///
    /// 如果返回值为 [`Ok(n)`]，则必须保证 `n <= buf.len()`。
    /// `0` 的返回值通常意味着基础 object 不再能够接受字节，并且可能也无法在 future 中接收，或者提供的缓冲区为空。
    ///
    ///
    /// # Errors
    ///
    /// 对 `write` 的每次调用都可能产生 I/O 错误，指示操作无法完成。如果返回错误，则缓冲区中没有字节写入此 writer。
    ///
    /// 如果无法将整个缓冲区写入此 writer，则不认为是错误。
    ///
    /// [`ErrorKind::Interrupted`] 类型的错误是非致命错误，如果没有其他事情可做，则应重试写入操作。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut buffer = File::create("foo.txt")?;
    ///
    ///     // 写入字节字符串的某些前缀，不一定要全部。
    ///     buffer.write(b"some bytes")?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// [`Ok(n)`]: Ok
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn write(&mut self, buf: &[u8]) -> Result<usize>;

    /// 类似于 [`write`]，不同之处在于它是从缓冲区片段中写入数据的。
    ///
    /// 数据是按顺序从每个缓冲区复制的，从中读取的最终缓冲区可能仅被部分消耗。
    /// 此方法必须与串联的缓冲区对 [`write`] 的调用相同。
    ///
    /// 默认实现使用提供的第一个非空缓冲区调用 [`write`]，如果不存在，则为空。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::IoSlice;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut data1 = [1; 8];
    ///     let mut data2 = [15; 8];
    ///     let io_slice1 = IoSlice::new(&mut data1);
    ///     let io_slice2 = IoSlice::new(&mut data2);
    ///
    ///     let mut buffer = File::create("foo.txt")?;
    ///
    ///     // 写入字节字符串的某些前缀，不一定要全部。
    ///     buffer.write_vectored(&[io_slice1, io_slice2])?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// [`write`]: Write::write
    ///
    #[stable(feature = "iovec", since = "1.36.0")]
    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize> {
        default_write_vectored(|b| self.write(b), bufs)
    }

    /// 确定此 `Write`r 是否具有有效的 [`write_vectored`] 实现。
    ///
    /// 如果 `Write`r 没有覆盖默认的 [`write_vectored`] 实现，则使用它的代码可能希望完全避免使用该方法，并合并写入单个缓冲区以提高性能。
    ///
    ///
    /// 默认实现返回 `false`。
    ///
    /// [`write_vectored`]: Write::write_vectored
    ///
    ///
    #[unstable(feature = "can_vector", issue = "69941")]
    fn is_write_vectored(&self) -> bool {
        false
    }

    /// 刷新此输出流，确保所有中间缓冲的内容均到达其目的地。
    ///
    ///
    /// # Errors
    ///
    /// 如果由于 I/O 错误或达到 EOF 而无法写入所有字节，则认为是错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::prelude::*;
    /// use std::io::BufWriter;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut buffer = BufWriter::new(File::create("foo.txt")?);
    ///
    ///     buffer.write_all(b"some bytes")?;
    ///     buffer.flush()?;
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn flush(&mut self) -> Result<()>;

    /// 尝试将整个缓冲区写入此 writer。
    ///
    /// 此方法将连续调用 [`write`]，直到没有更多数据要写入或返回非 [`ErrorKind::Interrupted`] 类型的错误为止。
    /// 在成功写入整个缓冲区或发生此类错误之前，此方法将不会返回。
    /// 从此方法生成的不是 [`ErrorKind::Interrupted`] 类型的第一个错误将被返回。
    ///
    /// 如果缓冲区不包含任何数据，则永远不会调用 [`write`]。
    ///
    /// # Errors
    ///
    /// 该函数将返回 [`write`] 返回的第一个非 -[`ErrorKind::Interrupted`] 类型的错误。
    ///
    /// [`write`]: Write::write
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut buffer = File::create("foo.txt")?;
    ///
    ///     buffer.write_all(b"some bytes")?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn write_all(&mut self, mut buf: &[u8]) -> Result<()> {
        while !buf.is_empty() {
            match self.write(buf) {
                Ok(0) => {
                    return Err(Error::new_const(
                        ErrorKind::WriteZero,
                        &"failed to write whole buffer",
                    ));
                }
                Ok(n) => buf = &buf[n..],
                Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
                Err(e) => return Err(e),
            }
        }
        Ok(())
    }

    /// 尝试将多个缓冲区写入此 writer。
    ///
    /// 此方法将连续调用 [`write_vectored`]，直到没有更多数据要写入或返回非 [`ErrorKind::Interrupted`] 类型的错误为止。
    ///
    /// 在成功写入所有缓冲区或发生此类错误之前，此方法将不会返回。
    /// 从此方法生成的不是 [`ErrorKind::Interrupted`] 类型的第一个错误将被返回。
    ///
    /// 如果缓冲区不包含任何数据，则永远不会调用 [`write_vectored`]。
    ///
    /// # Notes
    ///
    /// 与 [`write_vectored`] 不同，这需要对 [`IoSlice`] 的切片进行 *可变* 引用，而不是不可变。
    /// 那是因为我们需要修改切片以跟踪已写入的字节。
    ///
    /// 此函数返回后，将不指定 `bufs` 的内容，这取决于需要对 [`write_vectored`] 进行多少次调用。
    /// 最好将此函数理解为拥有 `bufs` 的所有权，并且此后不使用 `bufs`。
    /// [IoSlice] 指向的基础缓冲区 (而不是 [IoSlice] 本身) 是不变的，可以重用。
    ///
    /// [`write_vectored`]: Write::write_vectored
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(write_all_vectored)]
    /// # fn main() -> std::io::Result<()> {
    ///
    /// use std::io::{Write, IoSlice};
    ///
    /// let mut writer = Vec::new();
    /// let bufs = &mut [
    ///     IoSlice::new(&[1]),
    ///     IoSlice::new(&[2, 3]),
    ///     IoSlice::new(&[4, 5, 6]),
    /// ];
    ///
    /// writer.write_all_vectored(bufs)?;
    /// // Note: `bufs` 的内容现在是不确定的，请参见说明部分。
    ///
    /// assert_eq!(writer, &[1, 2, 3, 4, 5, 6]);
    /// # Ok(()) }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "write_all_vectored", issue = "70436")]
    fn write_all_vectored(&mut self, mut bufs: &mut [IoSlice<'_>]) -> Result<()> {
        // 如果 bufs 不包含任何数据，请确保它为空，以避免在没有要写入的数据时调用 write_vectored。
        //
        IoSlice::advance_slices(&mut bufs, 0);
        while !bufs.is_empty() {
            match self.write_vectored(bufs) {
                Ok(0) => {
                    return Err(Error::new_const(
                        ErrorKind::WriteZero,
                        &"failed to write whole buffer",
                    ));
                }
                Ok(n) => IoSlice::advance_slices(&mut bufs, n),
                Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
                Err(e) => return Err(e),
            }
        }
        Ok(())
    }

    /// 将格式化的字符串写入此 writer，返回遇到的任何错误。
    ///
    /// 该方法主要用于与 [`format_args!()`] 宏进行接口连接，但是很少需要显式调用它。
    /// 应优先使用 [`write!()`] 宏来调用此方法。
    ///
    /// 此函数内部在此 trait 上使用 [`write_all`] 方法，因此只要没有收到错误，就将连续写入数据。
    ///
    /// 这也意味着此签名中未指示部分写入。
    ///
    /// [`write_all`]: Write::write_all
    ///
    /// # Errors
    ///
    /// 此函数将返回格式化时报告的任何 I/O 错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut buffer = File::create("foo.txt")?;
    ///
    ///     // 这个
    ///     write!(buffer, "{:.*}", 2, 1.234567)?;
    ///     // 变成这样:
    ///     buffer.write_fmt(format_args!("{:.*}", 2, 1.234567))?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> Result<()> {
        // 创建一个垫片，该垫片将 Write 转换为 fmt::Write 并避免 I/O 错误。
        // 而不是丢弃它们
        struct Adaptor<'a, T: ?Sized + 'a> {
            inner: &'a mut T,
            error: Result<()>,
        }

        impl<T: Write + ?Sized> fmt::Write for Adaptor<'_, T> {
            fn write_str(&mut self, s: &str) -> fmt::Result {
                match self.inner.write_all(s.as_bytes()) {
                    Ok(()) => Ok(()),
                    Err(e) => {
                        self.error = Err(e);
                        Err(fmt::Error)
                    }
                }
            }
        }

        let mut output = Adaptor { inner: self, error: Ok(()) };
        match fmt::write(&mut output, fmt) {
            Ok(()) => Ok(()),
            Err(..) => {
                // 检查错误是否来自基础 `Write`
                if output.error.is_err() {
                    output.error
                } else {
                    Err(Error::new_const(ErrorKind::Uncategorized, &"formatter error"))
                }
            }
        }
    }

    /// 为此 `Write` 实例创建 "by reference" 适配器。
    ///
    /// 返回的适配器还实现了 `Write`，将仅借用此当前的 writer。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::Write;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut buffer = File::create("foo.txt")?;
    ///
    ///     let reference = buffer.by_ref();
    ///
    ///     // 我们可以像使用原始缓冲区一样使用引用
    ///     reference.write_all(b"some bytes")?;
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn by_ref(&mut self) -> &mut Self
    where
        Self: Sized,
    {
        self
    }
}

/// `Seek` trait 提供了一个游标，可以在字节流中移动它。
///
/// 流通常具有固定的大小，允许相对于端点或当前偏移量进行搜索。
///
///
/// # Examples
///
/// [`File`] 的工具 `Seek`:
///
/// [`File`]: crate::fs::File
///
/// ```no_run
/// use std::io;
/// use std::io::prelude::*;
/// use std::fs::File;
/// use std::io::SeekFrom;
///
/// fn main() -> io::Result<()> {
///     let mut f = File::open("foo.txt")?;
///
///     // 从文件的开头将游标移动 42 个字节
///     f.seek(SeekFrom::Start(42))?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Seek {
    /// 在流中寻找以字节为单位的偏移量。
    ///
    /// 允许在流的末尾进行查找，但是行为由实现定义。
    ///
    /// 如果查找操作成功完成，则此方法从流的开头返回新位置。
    ///
    /// 该位置以后可以与 [`SeekFrom::Start`] 一起使用。
    ///
    /// # Errors
    ///
    /// 查找可能会失败，例如因为它可能涉及刷新缓冲区。
    ///
    /// 寻求负偏移被认为是错误。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn seek(&mut self, pos: SeekFrom) -> Result<u64>;

    /// 返回到流的开头。
    ///
    /// 这是一个方便的方法，相当于 `seek(SeekFrom::Start(0))`。
    ///
    /// # Errors
    ///
    /// 返回可能会失败，例如因为它可能涉及刷新缓冲区。
    ///
    /// # Example
    ///
    /// ```no_run
    /// use std::io::{Read, Seek, Write};
    /// use std::fs::OpenOptions;
    ///
    /// let mut f = OpenOptions::new()
    ///     .write(true)
    ///     .read(true)
    ///     .create(true)
    ///     .open("foo.txt").unwrap();
    ///
    /// let hello = "Hello!\n";
    /// write!(f, "{}", hello).unwrap();
    /// f.rewind().unwrap();
    ///
    /// let mut buf = String::new();
    /// f.read_to_string(&mut buf).unwrap();
    /// assert_eq!(&buf, hello);
    /// ```
    #[stable(feature = "seek_rewind", since = "1.55.0")]
    fn rewind(&mut self) -> Result<()> {
        self.seek(SeekFrom::Start(0))?;
        Ok(())
    }

    /// 返回此流的长度 (以字节为单位)。
    ///
    /// 此方法最多使用三个查找操作来实现。如果此方法成功返回，则搜索位置不变 (即，调用此方法之前的位置与之后的位置相同)。
    /// 但是，如果此方法返回错误，则未指定搜索位置。
    ///
    /// 如果您需要获取 *多个* 流的长度，并且以后不再关心查找位置，则可以通过简单地调用 `seek(SeekFrom::End(0))` 并使用其返回值 (它也是流的长度) 来减少查找操作的次数。
    ///
    ///
    /// 请注意，流的长度可以随时间变化 (例如，将数据附加到文件时)。因此，多次调用此方法不一定每次都返回相同的长度。
    ///
    /// # Example
    ///
    /// ```no_run
    /// #![feature(seek_stream_len)]
    /// use std::{
    ///     io::{self, Seek},
    ///     fs::File,
    /// };
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///
    ///     let len = f.stream_len()?;
    ///     println!("The file is currently {} bytes long", len);
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "seek_stream_len", issue = "59359")]
    fn stream_len(&mut self) -> Result<u64> {
        let old_pos = self.stream_position()?;
        let len = self.seek(SeekFrom::End(0))?;

        // 当我们已经走到尽头时，请避免再寻求第三次机会。
        // 分支通常比查找操作便宜。
        if old_pos != len {
            self.seek(SeekFrom::Start(old_pos))?;
        }

        Ok(len)
    }

    /// 从流的开头返回当前搜索位置。
    ///
    /// 这等效于 `self.seek(SeekFrom::Current(0))`。
    ///
    /// # Example
    ///
    /// ```no_run
    /// use std::{
    ///     io::{self, BufRead, BufReader, Seek},
    ///     fs::File,
    /// };
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut f = BufReader::new(File::open("foo.txt")?);
    ///
    ///     let before = f.stream_position()?;
    ///     f.read_line(&mut String::new())?;
    ///     let after = f.stream_position()?;
    ///
    ///     println!("The first line was {} bytes long", after - before);
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "seek_convenience", since = "1.51.0")]
    fn stream_position(&mut self) -> Result<u64> {
        self.seek(SeekFrom::Current(0))
    }
}

/// 列举可能在 I/O object 中进行搜索的方法。
///
/// [`Seek`] trait 使用它。
#[derive(Copy, PartialEq, Eq, Clone, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum SeekFrom {
    /// 将偏移量设置为提供的字节数。
    #[stable(feature = "rust1", since = "1.0.0")]
    Start(#[stable(feature = "rust1", since = "1.0.0")] u64),

    /// 将偏移量设置为此 object 的大小加上指定的字节数。
    ///
    /// 可以在 object 的末尾进行查找，但是在字节 0 之前进行查找是错误的。
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    End(#[stable(feature = "rust1", since = "1.0.0")] i64),

    /// 将偏移量设置为当前位置加上指定的字节数。
    ///
    /// 可以在 object 的末尾进行查找，但是在字节 0 之前进行查找是错误的。
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Current(#[stable(feature = "rust1", since = "1.0.0")] i64),
}

fn read_until<R: BufRead + ?Sized>(r: &mut R, delim: u8, buf: &mut Vec<u8>) -> Result<usize> {
    let mut read = 0;
    loop {
        let (done, used) = {
            let available = match r.fill_buf() {
                Ok(n) => n,
                Err(ref e) if e.kind() == ErrorKind::Interrupted => continue,
                Err(e) => return Err(e),
            };
            match memchr::memchr(delim, available) {
                Some(i) => {
                    buf.extend_from_slice(&available[..=i]);
                    (true, i + 1)
                }
                None => {
                    buf.extend_from_slice(available);
                    (false, available.len())
                }
            }
        };
        r.consume(used);
        read += used;
        if done || used == 0 {
            return Ok(read);
        }
    }
}

/// `BufRead` 是带有内部缓冲区的 `Read` 类型，它可以执行其他读取方式。
///
/// 例如，在不使用缓冲区的情况下，逐行读取效率很低，因此，如果要逐行读取，则需要 `BufRead`，其中包括 [`read_line`] 方法和 [`lines`] 迭代器。
///
///
/// # Examples
///
/// 锁定的标准输入实现 `BufRead`:
///
/// ```no_run
/// use std::io;
/// use std::io::prelude::*;
///
/// let stdin = io::stdin();
/// for line in stdin.lock().lines() {
///     println!("{}", line.unwrap());
/// }
/// ```
///
/// 如果您具有实现 [`Read`] 的功能，则可以使用 [`BufReader` type][`BufReader`] 将其转换为 `BufRead`。
///
/// 例如，[`File`] 实现 [`Read`]，但不实现 `BufRead`。
/// [`BufReader`] 抢救!
///
/// [`File`]: crate::fs::File
/// [`read_line`]: BufRead::read_line
/// [`lines`]: BufRead::lines
///
/// ```no_run
/// use std::io::{self, BufReader};
/// use std::io::prelude::*;
/// use std::fs::File;
///
/// fn main() -> io::Result<()> {
///     let f = File::open("foo.txt")?;
///     let f = BufReader::new(f);
///
///     for line in f.lines() {
///         println!("{}", line.unwrap());
///     }
///
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait BufRead: Read {
    /// 返回内部缓冲区的内容，如果内部缓冲区为空，则使用内部 reader 中的更多数据填充内部缓冲区。
    ///
    /// 此函数是较低级别的调用。它需要与 [`consume`] 方法配对才能正确执行功能。
    /// 当调用此方法时，任何内容都不是 "read"，因为稍后调用 `read` 可能会返回相同的内容。
    /// 因此，必须使用此缓冲区消耗的字节数来调用 [`consume`]，以确保字节永远不会返回两次。
    ///
    ///
    /// [`consume`]: BufRead::consume
    ///
    /// 返回的空缓冲区表示流已达到 EOF。
    ///
    /// # Errors
    ///
    /// 如果已读取基础 reader，但此函数返回错误，则此函数将返回 I/O 错误。
    ///
    /// # Examples
    ///
    /// 锁定的标准输入实现 `BufRead`:
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    ///
    /// let stdin = io::stdin();
    /// let mut stdin = stdin.lock();
    ///
    /// let buffer = stdin.fill_buf().unwrap();
    ///
    /// // 使用缓冲区
    /// println!("{:?}", buffer);
    ///
    /// // 确保我们处理过的字节以后不再返回
    /// let length = buffer.len();
    /// stdin.consume(length);
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fill_buf(&mut self) -> Result<&[u8]>;

    /// 告诉此缓冲区 `amt` 字节已从缓冲区中消耗掉，因此在调用 `read` 时不再应返回它们。
    ///
    /// 此函数是较低级别的调用。需要配合 [`fill_buf`] 方法才能正常使用。
    /// 该函数不执行任何 I/O，它只是通知 object 从 [`fill_buf`] 返回的某些缓冲区已被消耗，不应再返回。
    ///
    /// 因此，如果在调用 [`fill_buf`] 之前未对其进行调用，则此函数可能会做一些奇怪的事情。
    ///
    /// `amt` 必须为 `<=`，即 [`fill_buf`] 返回的缓冲区中的字节数。
    ///
    /// # Examples
    ///
    /// 由于 `consume()` 旨在与 [`fill_buf`] 一起使用，因此该方法的示例包括 `consume()` 的示例。
    ///
    /// [`fill_buf`]: BufRead::fill_buf
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn consume(&mut self, amt: usize);

    /// 检查底层 `Read` 是否有任何数据可供读取。
    ///
    /// 这个函数可能会填充缓冲区来检查数据，所以这个函数返回的是 `Result<bool>`，而不是 `bool`。
    ///
    /// 默认实现调用 `fill_buf` 并检查返回的 4 为空 (这意味着没有数据剩余，因为达到了 EOF)。
    ///
    ///
    /// Examples
    ///
    /// ```
    /// #![feature(buf_read_has_data_left)]
    /// use std::io;
    /// use std::io::prelude::*;
    ///
    /// let stdin = io::stdin();
    /// let mut stdin = stdin.lock();
    ///
    /// while stdin.has_data_left().unwrap() {
    ///     let mut line = String::new();
    ///     stdin.read_line(&mut line).unwrap();
    ///     // 与行一起工作
    ///     println!("{:?}", line);
    /// }
    /// ```
    ///
    ///
    #[unstable(feature = "buf_read_has_data_left", reason = "recently added", issue = "86423")]
    fn has_data_left(&mut self) -> Result<bool> {
        self.fill_buf().map(|b| !b.is_empty())
    }

    /// 将所有字节读入 `buf`，直到到达定界符 `byte` 或 EOF。
    ///
    /// 该函数将从底层流中读取字节，直到找到定界符或 EOF。
    /// 一旦找到，定界符 (包括定界符) 之前 (包括找到) 的所有字节都将附加到 `buf`。
    ///
    /// 如果成功，此函数将返回读取的字节总数。
    ///
    /// 该函数正在阻塞，应谨慎使用: 攻击者有可能连续发送字节而无需发送定界符或 EOF。
    ///
    ///
    /// # Errors
    ///
    /// 该函数将忽略 [`ErrorKind::Interrupted`] 的所有实例，否则将返回 [`fill_buf`] 返回的任何错误。
    ///
    /// 如果遇到 I/O 错误，则 `buf` 中将存在到目前为止已读取的所有字节，并且已对其长度进行了适当的调整。
    ///
    /// [`fill_buf`]: BufRead::fill_buf
    ///
    /// # Examples
    ///
    /// [`std::io::Cursor`][`Cursor`] 是实现 `BufRead` 的类型。
    /// 在此示例中，我们使用 [`Cursor`] 读取以连字符分隔的段中的字节片中的所有字节:
    ///
    /// ```
    /// use std::io::{self, BufRead};
    ///
    /// let mut cursor = io::Cursor::new(b"lorem-ipsum");
    /// let mut buf = vec![];
    ///
    /// // 游标在 'l'
    /// let num_bytes = cursor.read_until(b'-', &mut buf)
    ///     .expect("reading from cursor won't fail");
    /// assert_eq!(num_bytes, 6);
    /// assert_eq!(buf, b"lorem-");
    /// buf.clear();
    ///
    /// // 游标在 'i'
    /// let num_bytes = cursor.read_until(b'-', &mut buf)
    ///     .expect("reading from cursor won't fail");
    /// assert_eq!(num_bytes, 5);
    /// assert_eq!(buf, b"ipsum");
    /// buf.clear();
    ///
    /// // 游标在 EOF 处
    /// let num_bytes = cursor.read_until(b'-', &mut buf)
    ///     .expect("reading from cursor won't fail");
    /// assert_eq!(num_bytes, 0);
    /// assert_eq!(buf, b"");
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize> {
        read_until(self, byte, buf)
    }

    /// 读取所有字节，直到到达换行符 (`0xA` 字节)，然后将它们附加到提供的缓冲区中。
    ///
    /// 该函数将从底层流中读取字节，直到找到换行符 (`0xA` 字节) 或 EOF。
    /// 一旦找到，定界符 (包括定界符) 之前 (包括找到) 的所有字节都将附加到 `buf`。
    ///
    /// 如果成功，此函数将返回读取的字节总数。
    ///
    /// 如果此函数返回 [`Ok(0)`]，则流已到达 EOF。
    ///
    /// 该函数正在阻塞，应谨慎使用: 攻击者有可能连续发送字节而无需发送换行符或 EOF。
    ///
    ///
    /// [`Ok(0)`]: Ok
    ///
    /// # Errors
    ///
    /// 该函数与 [`read_until`] 具有相同的错误语义，如果读取的字节无效，则还将返回错误。
    /// 如果遇到 I/O 错误，则 `buf` 可能包含一些已读取的字节，如果到目前为止读取的所有数据都是有效的 UTF-8。
    ///
    /// [`read_until`]: BufRead::read_until
    ///
    /// # Examples
    ///
    /// [`std::io::Cursor`][`Cursor`] 是实现 `BufRead` 的类型。在这个例子中，我们使用 [`Cursor`] 读取一个字节中的所有行:
    ///
    /// ```
    /// use std::io::{self, BufRead};
    ///
    /// let mut cursor = io::Cursor::new(b"foo\nbar");
    /// let mut buf = String::new();
    ///
    /// // 游标在 'f'
    /// let num_bytes = cursor.read_line(&mut buf)
    ///     .expect("reading from cursor won't fail");
    /// assert_eq!(num_bytes, 4);
    /// assert_eq!(buf, "foo\n");
    /// buf.clear();
    ///
    /// // 游标在 'b'
    /// let num_bytes = cursor.read_line(&mut buf)
    ///     .expect("reading from cursor won't fail");
    /// assert_eq!(num_bytes, 3);
    /// assert_eq!(buf, "bar");
    /// buf.clear();
    ///
    /// // 游标在 EOF 处
    /// let num_bytes = cursor.read_line(&mut buf)
    ///     .expect("reading from cursor won't fail");
    /// assert_eq!(num_bytes, 0);
    /// assert_eq!(buf, "");
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn read_line(&mut self, buf: &mut String) -> Result<usize> {
        // 请注意，我们不是在这里调用 `.read_until` 方法，而是我们的硬编码实现。
        // 有关原因的更多详细信息，请参见 `read_to_end` 中的注释。
        //
        append_to_string(buf, |b| read_until(self, b'\n', b))
    }

    /// 返回对该字节 `byte` 上的 reader 拆分内容的迭代器。
    ///
    /// 从此函数返回的迭代器将返回 [`io::Result`]`<`[`Vec<u8>`]`>` 的实例。
    ///
    /// 返回的每个 vector 都不会在末尾有定界符字节。
    ///
    /// 只要 [`read_until`] 也产生错误，此函数就会产生错误。
    ///
    /// [`io::Result`]: self::Result
    /// [`read_until`]: BufRead::read_until
    ///
    /// # Examples
    ///
    /// [`std::io::Cursor`][`Cursor`] 是实现 `BufRead` 的类型。
    /// 在此示例中，我们使用 [`Cursor`] 遍历字节切片中的所有连字符分隔的段
    ///
    /// ```
    /// use std::io::{self, BufRead};
    ///
    /// let cursor = io::Cursor::new(b"lorem-ipsum-dolor");
    ///
    /// let mut split_iter = cursor.split(b'-').map(|l| l.unwrap());
    /// assert_eq!(split_iter.next(), Some(b"lorem".to_vec()));
    /// assert_eq!(split_iter.next(), Some(b"ipsum".to_vec()));
    /// assert_eq!(split_iter.next(), Some(b"dolor".to_vec()));
    /// assert_eq!(split_iter.next(), None);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn split(self, byte: u8) -> Split<Self>
    where
        Self: Sized,
    {
        Split { buf: self, delim: byte }
    }

    /// 返回此 reader 的各行上的迭代器。
    ///
    /// 从此函数返回的迭代器将产生 [`io::Result`]`<`[`String`]`>` 的实例。
    /// 返回的每个字符串 *不会* 在末尾有换行符 (`0xA` 字节) 或 `CRLF` (`0xD`，`0xA` 字节)。
    ///
    ///
    /// [`io::Result`]: self::Result
    ///
    /// # Examples
    ///
    /// [`std::io::Cursor`][`Cursor`] 是实现 `BufRead` 的类型。
    /// 在此示例中，我们使用 [`Cursor`] 遍历字节切片中的所有行。
    ///
    /// ```
    /// use std::io::{self, BufRead};
    ///
    /// let cursor = io::Cursor::new(b"lorem\nipsum\r\ndolor");
    ///
    /// let mut lines_iter = cursor.lines().map(|l| l.unwrap());
    /// assert_eq!(lines_iter.next(), Some(String::from("lorem")));
    /// assert_eq!(lines_iter.next(), Some(String::from("ipsum")));
    /// assert_eq!(lines_iter.next(), Some(String::from("dolor")));
    /// assert_eq!(lines_iter.next(), None);
    /// ```
    ///
    /// # Errors
    ///
    /// 迭代器的每一行都具有与 [`BufRead::read_line`] 相同的错误语义。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn lines(self) -> Lines<Self>
    where
        Self: Sized,
    {
        Lines { buf: self }
    }
}

/// 将两个 readers 链接在一起的适配器。
///
/// 通常通过在 reader 上调用 [`chain`] 来创建此结构体。
/// 请参见 [`chain`] 的文档以获取更多详细信息。
///
/// [`chain`]: Read::chain
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Chain<T, U> {
    first: T,
    second: U,
    done_first: bool,
}

impl<T, U> Chain<T, U> {
    /// 消耗 `Chain`，返回包装的 readers。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut foo_file = File::open("foo.txt")?;
    ///     let mut bar_file = File::open("bar.txt")?;
    ///
    ///     let chain = foo_file.chain(bar_file);
    ///     let (foo_file, bar_file) = chain.into_inner();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
    pub fn into_inner(self) -> (T, U) {
        (self.first, self.second)
    }

    /// 在此 `Chain` 中获得对基础 readers 的引用。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut foo_file = File::open("foo.txt")?;
    ///     let mut bar_file = File::open("bar.txt")?;
    ///
    ///     let chain = foo_file.chain(bar_file);
    ///     let (foo_file, bar_file) = chain.get_ref();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
    pub fn get_ref(&self) -> (&T, &U) {
        (&self.first, &self.second)
    }

    /// 获取此 `Chain` 中基础 readers 的可变引用。
    ///
    /// 应注意避免修改基础 readers 的内部 I/O 状态，因为这样做可能会破坏该 `Chain` 的内部状态。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut foo_file = File::open("foo.txt")?;
    ///     let mut bar_file = File::open("bar.txt")?;
    ///
    ///     let mut chain = foo_file.chain(bar_file);
    ///     let (foo_file, bar_file) = chain.get_mut();
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
    pub fn get_mut(&mut self) -> (&mut T, &mut U) {
        (&mut self.first, &mut self.second)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Read, U: Read> Read for Chain<T, U> {
    fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
        if !self.done_first {
            match self.first.read(buf)? {
                0 if !buf.is_empty() => self.done_first = true,
                n => return Ok(n),
            }
        }
        self.second.read(buf)
    }

    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize> {
        if !self.done_first {
            match self.first.read_vectored(bufs)? {
                0 if bufs.iter().any(|b| !b.is_empty()) => self.done_first = true,
                n => return Ok(n),
            }
        }
        self.second.read_vectored(bufs)
    }

    unsafe fn initializer(&self) -> Initializer {
        let initializer = self.first.initializer();
        if initializer.should_initialize() { initializer } else { self.second.initializer() }
    }
}

#[stable(feature = "chain_bufread", since = "1.9.0")]
impl<T: BufRead, U: BufRead> BufRead for Chain<T, U> {
    fn fill_buf(&mut self) -> Result<&[u8]> {
        if !self.done_first {
            match self.first.fill_buf()? {
                buf if buf.is_empty() => {
                    self.done_first = true;
                }
                buf => return Ok(buf),
            }
        }
        self.second.fill_buf()
    }

    fn consume(&mut self, amt: usize) {
        if !self.done_first { self.first.consume(amt) } else { self.second.consume(amt) }
    }
}

impl<T, U> SizeHint for Chain<T, U> {
    #[inline]
    fn lower_bound(&self) -> usize {
        SizeHint::lower_bound(&self.first) + SizeHint::lower_bound(&self.second)
    }

    #[inline]
    fn upper_bound(&self) -> Option<usize> {
        match (SizeHint::upper_bound(&self.first), SizeHint::upper_bound(&self.second)) {
            (Some(first), Some(second)) => first.checked_add(second),
            _ => None,
        }
    }
}

/// Reader 适配器，用于限制从基础 reader 读取的字节。
///
/// 通常通过在 reader 上调用 [`take`] 来创建此结构体。
/// 请参见 [`take`] 的文档以获取更多详细信息。
///
/// [`take`]: Read::take
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Take<T> {
    inner: T,
    limit: u64,
}

impl<T> Take<T> {
    /// 返回在此实例返回 EOF 之前可以读取的字节数。
    ///
    /// # Note
    ///
    /// 如果基础 [`Read`] 实例达到 EOF，则在读取的字节数少于此方法指示的字节数之后，此实例可能到达 `EOF`。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let f = File::open("foo.txt")?;
    ///
    ///     // 最多读取五个字节
    ///     let handle = f.take(5);
    ///
    ///     println!("limit: {}", handle.limit());
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn limit(&self) -> u64 {
        self.limit
    }

    /// 设置在此实例返回 EOF 之前可以读取的字节数。
    /// 这与构造新的 `Take` 实例相同，因此在调用此方法时，读取的字节数和先前的限制值无关紧要。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let f = File::open("foo.txt")?;
    ///
    ///     // 最多读取五个字节
    ///     let mut handle = f.take(5);
    ///     handle.set_limit(10);
    ///
    ///     assert_eq!(handle.limit(), 10);
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "take_set_limit", since = "1.27.0")]
    pub fn set_limit(&mut self, limit: u64) {
        self.limit = limit;
    }

    /// 消耗 `Take`，返回包装的 reader。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///
    ///     let mut buffer = [0; 5];
    ///     let mut handle = file.take(5);
    ///     handle.read(&mut buffer)?;
    ///
    ///     let file = handle.into_inner();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "io_take_into_inner", since = "1.15.0")]
    pub fn into_inner(self) -> T {
        self.inner
    }

    /// 获取对基础 reader 的引用。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///
    ///     let mut buffer = [0; 5];
    ///     let mut handle = file.take(5);
    ///     handle.read(&mut buffer)?;
    ///
    ///     let file = handle.get_ref();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
    pub fn get_ref(&self) -> &T {
        &self.inner
    }

    /// 获取基础 reader 的可变引用。
    ///
    /// 应注意避免修改基础 reader 的内部 I/O 状态，因为这样做可能会破坏该 `Take` 的内部限制。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///
    ///     let mut buffer = [0; 5];
    ///     let mut handle = file.take(5);
    ///     handle.read(&mut buffer)?;
    ///
    ///     let file = handle.get_mut();
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
    pub fn get_mut(&mut self) -> &mut T {
        &mut self.inner
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Read> Read for Take<T> {
    fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
        // 在 EOF 根本不要调用内部 reader，因为它可能仍然会阻塞
        if self.limit == 0 {
            return Ok(0);
        }

        let max = cmp::min(buf.len() as u64, self.limit) as usize;
        let n = self.inner.read(&mut buf[..max])?;
        self.limit -= n as u64;
        Ok(n)
    }

    unsafe fn initializer(&self) -> Initializer {
        self.inner.initializer()
    }

    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
        // 传递一个 reserve_size 闭包，该包尊重每次读取的 limit 的当前值。
        // 如果我们达到读取限制，这将阻止最终的零字节读取再次分配。
        //
        read_to_end_with_reservation(self, buf, |self_| cmp::min(self_.limit, 32) as usize)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: BufRead> BufRead for Take<T> {
    fn fill_buf(&mut self) -> Result<&[u8]> {
        // 在 EOF 根本不要调用内部 reader，因为它可能仍然会阻塞
        if self.limit == 0 {
            return Ok(&[]);
        }

        let buf = self.inner.fill_buf()?;
        let cap = cmp::min(buf.len() as u64, self.limit) as usize;
        Ok(&buf[..cap])
    }

    fn consume(&mut self, amt: usize) {
        // 不要让调用者通过传递超大值来重置限制
        let amt = cmp::min(amt as u64, self.limit) as usize;
        self.limit -= amt as u64;
        self.inner.consume(amt);
    }
}

impl<T> SizeHint for Take<T> {
    #[inline]
    fn lower_bound(&self) -> usize {
        cmp::min(SizeHint::lower_bound(&self.inner) as u64, self.limit) as usize
    }

    #[inline]
    fn upper_bound(&self) -> Option<usize> {
        match SizeHint::upper_bound(&self.inner) {
            Some(upper_bound) => Some(cmp::min(upper_bound as u64, self.limit) as usize),
            None => self.limit.try_into().ok(),
        }
    }
}

/// reader 的 `u8` 值上的迭代器。
///
/// 通常通过在 reader 上调用 [`bytes`] 来创建此结构体。
/// 请参见 [`bytes`] 的文档以获取更多详细信息。
///
/// [`bytes`]: Read::bytes
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Bytes<R> {
    inner: R,
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<R: Read> Iterator for Bytes<R> {
    type Item = Result<u8>;

    fn next(&mut self) -> Option<Result<u8>> {
        let mut byte = 0;
        loop {
            return match self.inner.read(slice::from_mut(&mut byte)) {
                Ok(0) => None,
                Ok(..) => Some(Ok(byte)),
                Err(ref e) if e.kind() == ErrorKind::Interrupted => continue,
                Err(e) => Some(Err(e)),
            };
        }
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        SizeHint::size_hint(&self.inner)
    }
}

trait SizeHint {
    fn lower_bound(&self) -> usize;

    fn upper_bound(&self) -> Option<usize>;

    fn size_hint(&self) -> (usize, Option<usize>) {
        (self.lower_bound(), self.upper_bound())
    }
}

impl<T> SizeHint for T {
    #[inline]
    default fn lower_bound(&self) -> usize {
        0
    }

    #[inline]
    default fn upper_bound(&self) -> Option<usize> {
        None
    }
}

impl<T> SizeHint for &mut T {
    #[inline]
    fn lower_bound(&self) -> usize {
        SizeHint::lower_bound(*self)
    }

    #[inline]
    fn upper_bound(&self) -> Option<usize> {
        SizeHint::upper_bound(*self)
    }
}

impl<T> SizeHint for Box<T> {
    #[inline]
    fn lower_bound(&self) -> usize {
        SizeHint::lower_bound(&**self)
    }

    #[inline]
    fn upper_bound(&self) -> Option<usize> {
        SizeHint::upper_bound(&**self)
    }
}

impl SizeHint for &[u8] {
    #[inline]
    fn lower_bound(&self) -> usize {
        self.len()
    }

    #[inline]
    fn upper_bound(&self) -> Option<usize> {
        Some(self.len())
    }
}

/// 对 `BufRead` 实例的内容进行迭代的迭代器，该实例在特定字节上拆分。
///
///
/// 通常通过在 `BufRead` 上调用 [`split`] 来创建此结构体。
/// 请参见 [`split`] 的文档以获取更多详细信息。
///
/// [`split`]: BufRead::split
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Split<B> {
    buf: B,
    delim: u8,
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<B: BufRead> Iterator for Split<B> {
    type Item = Result<Vec<u8>>;

    fn next(&mut self) -> Option<Result<Vec<u8>>> {
        let mut buf = Vec::new();
        match self.buf.read_until(self.delim, &mut buf) {
            Ok(0) => None,
            Ok(_n) => {
                if buf[buf.len() - 1] == self.delim {
                    buf.pop();
                }
                Some(Ok(buf))
            }
            Err(e) => Some(Err(e)),
        }
    }
}

/// `BufRead` 实例的行上的迭代器。
///
/// 通常通过在 `BufRead` 上调用 [`lines`] 来创建此结构体。
/// 请参见 [`lines`] 的文档以获取更多详细信息。
///
/// [`lines`]: BufRead::lines
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Lines<B> {
    buf: B,
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<B: BufRead> Iterator for Lines<B> {
    type Item = Result<String>;

    fn next(&mut self) -> Option<Result<String>> {
        let mut buf = String::new();
        match self.buf.read_line(&mut buf) {
            Ok(0) => None,
            Ok(_n) => {
                if buf.ends_with('\n') {
                    buf.pop();
                    if buf.ends_with('\r') {
                        buf.pop();
                    }
                }
                Some(Ok(buf))
            }
            Err(e) => Some(Err(e)),
        }
    }
}