//! 核心 I/O 功能的 Traits，帮助程序和类型定义。
//!
//! `std::io` 模块包含许多在执行输入和输出时需要的常见操作。
//! 该模块中最核心的部分是 [`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::fmt;
use crate::mem::take;
use crate::ops::{Deref, DerefMut};
use crate::slice;
use crate::str;
use crate::sys;
use crate::sys_common::memchr;

#[stable(feature = "bufwriter_into_parts", since = "1.56.0")]
pub use self::buffered::WriterPanicked;
#[unstable(feature = "raw_os_error_ty", issue = "107792")]
pub use self::error::RawOsError;
pub(crate) use self::stdio::attempt_print_to_stderr;
#[unstable(feature = "internal_output_capture", issue = "none")]
#[doc(no_inline, hidden)]
pub use self::stdio::set_output_capture;
#[stable(feature = "is_terminal", since = "1.70.0")]
pub use self::stdio::IsTerminal;
#[unstable(feature = "print_internals", issue = "none")]
pub use self::stdio::{_eprint, _print};
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::{
    buffered::{BufReader, BufWriter, IntoInnerError, LineWriter},
    copy::copy,
    cursor::Cursor,
    error::{Error, ErrorKind, Result},
    stdio::{stderr, stdin, stdout, Stderr, StderrLock, Stdin, StdinLock, Stdout, StdoutLock},
    util::{empty, repeat, sink, Empty, Repeat, Sink},
};

#[unstable(feature = "read_buf", issue = "78485")]
pub use self::readbuf::{BorrowedBuf, BorrowedCursor};
pub(crate) use error::const_io_error;

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

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

pub(crate) use 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 数据，我们将得到未定义的行为。
//
//
//
//
//
//
//
//
pub(crate) unsafe fn append_to_string<F>(buf: &mut String, f: F) -> Result<usize>
where
    F: FnOnce(&mut Vec<u8>) -> Result<usize>,
{
    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::const_io_error!(
                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 倍。
//
//
//
pub(crate) fn default_read_to_end<R: Read + ?Sized>(
    r: &mut R,
    buf: &mut Vec<u8>,
    size_hint: Option<usize>,
) -> Result<usize> {
    let start_len = buf.len();
    let start_cap = buf.capacity();
    // 可选择限制每次迭代读取的最大字节数。
    // 这增加了一个任意的小提琴因子以允许比我们预期更多的数据。
    let max_read_size =
        size_hint.and_then(|s| s.checked_add(1024)?.checked_next_multiple_of(DEFAULT_BUF_SIZE));

    let mut initialized = 0; // 来自先前循环迭代的额外初始化字节
    loop {
        if buf.len() == buf.capacity() {
            buf.reserve(32); // buf 已满，需要更多空间
        }

        let mut spare = buf.spare_capacity_mut();
        if let Some(size) = max_read_size {
            let len = cmp::min(spare.len(), size);
            spare = &mut spare[..len]
        }
        let mut read_buf: BorrowedBuf<'_> = spare.into();

        // SAFETY: 这些字节已初始化，但未在上一个循环中填充
        unsafe {
            read_buf.set_init(initialized);
        }

        let mut cursor = read_buf.unfilled();
        match r.read_buf(cursor.reborrow()) {
            Ok(()) => {}
            Err(e) if e.kind() == ErrorKind::Interrupted => continue,
            Err(e) => return Err(e),
        }

        if cursor.written() == 0 {
            return Ok(buf.len() - start_len);
        }

        // 存储多少已初始化但未填充
        initialized = cursor.init_ref().len();

        // SAFETY: BorrowedBuf 的不，变体，意味着初始化了这么多内存。
        unsafe {
            let new_len = read_buf.filled().len() + buf.len();
            buf.set_len(new_len);
        }

        if buf.len() == buf.capacity() && buf.capacity() == start_cap {
            // 缓冲区可能是完全合适的。
            // 让我们读入一个探测缓冲区，看看它是否返回 `Ok(0)`。
            // 如果是这样，我们就避免了不必要的容量翻倍。
            // 但如果没有，请将探测缓冲区追加到主缓冲区，并增加它的容量。
            let mut probe = [0u8; 32];

            loop {
                match r.read(&mut probe) {
                    Ok(0) => return Ok(buf.len() - start_len),
                    Ok(n) => {
                        buf.extend_from_slice(&probe[..n]);
                        break;
                    }
                    Err(ref e) if e.kind() == ErrorKind::Interrupted => continue,
                    Err(e) => return Err(e),
                }
            }
        }
    }
}

pub(crate) fn default_read_to_string<R: Read + ?Sized>(
    r: &mut R,
    buf: &mut String,
    size_hint: Option<usize>,
) -> Result<usize> {
    // 请注意，我们在这里不调用 `r.read_to_end()`。我们将 `&mut Vec<u8>` (`buf` 的原始内容) 传递给 `read_to_end` 方法以填充它。
    // 任意实现都可以覆盖 vector 的全部内容，而不仅仅是追加到 vector (这是我们所期望的)。
    //
    // 为了防止额外检查整个缓冲区的 UTF-8-ness，我们将它传递给我们的硬编码 `default_read_to_end` 实现，我们知道它保证只将数据读入缓冲区的末尾。
    //
    //
    //
    //
    //
    unsafe { append_to_string(buf, |b| default_read_to_end(r, b, size_hint)) }
}

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::const_io_error!(ErrorKind::UnexpectedEof, "failed to fill whole buffer"))
    } else {
        Ok(())
    }
}

pub(crate) fn default_read_buf<F>(read: F, mut cursor: BorrowedCursor<'_>) -> Result<()>
where
    F: FnOnce(&mut [u8]) -> Result<usize>,
{
    let n = read(cursor.ensure_init().init_mut())?;
    unsafe {
        // SAFETY: 我们使用 `ensure_init` 进行了初始化，因此没有 uninit 数据可以前进。
        cursor.advance(n);
    }
    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 {
    /// 从该源中提取一些字节到指定的缓冲区中，返回读取的字节数。
    ///
    /// 该函数不提供有关是否阻塞等待数据的任何保证，但是如果对象需要阻塞读取而不能阻塞，则通常会通过 [`Err`] 返回值来发出信号。
    ///
    ///
    /// 如果此方法的返回值为 [`Ok(n)`]，则实现必须保证 `0 <= n <= buf.len()`。
    /// `n` 值非零表示缓冲区 `buf` 已填充有来自该源的 `n` 字节的数据。
    /// 如果 `n` 是 `0`，则它可以指示以下两种情况之一：
    ///
    /// 1. reader 已到达其 "文件结尾"，可能不再能够产生字节。请注意，这并不意味着 reader 总是会不再能够生成字节。
    /// 例如，在 Linux 上，此方法将调用 [`TcpStream`] 的 `recv` 系统调用，其中返回零表示连接已正确关闭。
    /// 而对于 [`File`]，有可能到达文件末尾并得到零作为结果，但如果向文件追加更多数据，那么将来对 `read` 的调用将返回更多数据。
    /// 2. 指定的缓冲区的长度为 0 个字节。
    ///
    /// 如果返回值 `n` 小于缓冲区大小，即使 reader 不在流的末尾，也不会出错。
    /// 例如，这可能是因为现在实际可用的字节较少 (例如，接近文件末尾) 或 read() 被信号中断。
    ///
    /// 由于此 trait 可以安全实现，因此不安全代码中的调用者不能依赖 `n <= buf.len()` 来确保安全。
    /// 当使用 `unsafe` 函数访问读取的字节时，需要格外小心。
    /// 调用者必须确保即使 `n > buf.len()` 也不能进行未经检查的越界访问。
    ///
    /// 调用此函数时，不保证 `buf` 的内容，因此实现不能依赖于 `buf` 内容的任何属性为真。
    /// 建议 `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
    }

    /// 读取所有字节，直到此源中的 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> {
        default_read_to_end(self, buf, None)
    }

    /// 读取这个源中的所有字节，直到 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> {
        default_read_to_string(self, buf, None)
    }

    /// 读取填充 `buf` 所需的确切字节数。
    ///
    /// 该函数读取所需的字节数以完全填充指定的缓冲区 `buf`。
    ///
    /// 调用此函数时，不保证 `buf` 的内容，因此实现不能依赖于 `buf` 内容的任何属性为真。
    /// 建议实现仅将数据写入 `buf`，而不读取其内容。
    /// [`read`] 上的文档对此主题有更详细的说明。
    ///
    /// # Errors
    ///
    /// 如果此函数遇到 [`ErrorKind::Interrupted`] 类型的错误，则该错误将被忽略，并且操作将继续。
    ///
    /// 如果此函数在完全填充缓冲区之前遇到 "文件结尾"，它将返回 [`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`](Read::read) 方法，只是它传递的是 [`BorrowedCursor`] 而不是 `[u8]` 以允许与未初始化的缓冲区一起使用。
    /// 新的数据将被追加到 `buf` 的任何现有内容中。
    ///
    /// 默认实现委托给 `read`。
    #[unstable(feature = "read_buf", issue = "78485")]
    fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<()> {
        default_read_buf(|b| self.read(b), buf)
    }

    /// 读取填充 `cursor` 所需的确切字节数。
    ///
    /// 这类似于 [`read_exact`](Read::read_exact) 方法，除了它传递的是 [`BorrowedCursor`] 而不是 `[u8]` 以允许使用未初始化的缓冲区。
    ///
    ///
    /// # Errors
    ///
    /// 如果此函数遇到 [`ErrorKind::Interrupted`] 类型的错误，则该错误将被忽略，并且操作将继续。
    ///
    /// 如果此函数在完全填充缓冲区之前遇到 "文件结尾"，它将返回 [`ErrorKind::UnexpectedEof`] 类型的错误。
    ///
    /// 如果遇到任何其他读取错误，则此函数立即返回。
    ///
    /// 如果此函数返回错误，则读取的所有字节都将，到 `cursor`。
    ///
    ///
    ///
    ///
    #[unstable(feature = "read_buf", issue = "78485")]
    fn read_buf_exact(&mut self, mut cursor: BorrowedCursor<'_>) -> Result<()> {
        while cursor.capacity() > 0 {
            let prev_written = cursor.written();
            match self.read_buf(cursor.reborrow()) {
                Ok(()) => {}
                Err(e) if e.kind() == ErrorKind::Interrupted => continue,
                Err(e) => return Err(e),
            }

            if cursor.written() == prev_written {
                return Err(Error::new(ErrorKind::UnexpectedEof, "failed to fill buffer"));
            }
        }

        Ok(())
    }

    /// 为这个 `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`] 是 <code>[Result]<[u8], [io::Error]></code>。
    /// 如果成功读取了一个字节，则产生的项为 [`Ok`]，否则为 [`Err`]。
    /// EOF 映射为从此迭代器返回 [`None`]。
    ///
    /// 默认实现为每个字节调用 `read`，这对于不在内存中的数据 (例如 [`File`]) 可能非常低效。
    ///
    /// 在这种情况下考虑使用 [`BufReader`]。
    ///
    /// # Examples
    ///
    /// [`File`] 的工具 `Read`：
    ///
    /// [`Item`]: Iterator::Item
    /// [`File`]: crate::fs::File "fs::File"
    /// [Result]: crate::result::Result "Result"
    /// [io::Error]: self::Error "io::Error"
    ///
    /// ```no_run
    /// use std::io;
    /// use std::io::prelude::*;
    /// use std::io::BufReader;
    /// use std::fs::File;
    ///
    /// fn main() -> io::Result<()> {
    ///     let f = BufReader::new(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` 实例将首先从该对象读取所有字节，直到遇到 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 f1 = File::open("foo.txt")?;
    ///     let 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 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 }
    }
}

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

    /// 在 slices 中推进一个切片。
    ///
    /// 缩小切片以删除任何完全超前的 `IoSliceMut`。
    /// 如果游标最终位于 `IoSliceMut` 的中间，则将其修改为从该游标处开始。
    ///
    /// 例如，如果我们有两个 8 字节的 `IoSliceMut` 的切片，并且我们提前 10 个字节，结果将只包括第二个 `IoSliceMut`，提前 2 个字节。
    ///
    ///
    /// # Panics
    ///
    /// 试图超越切片末端时出现 panic。
    ///
    /// # 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 take(bufs)[remove..];
        if bufs.is_empty() {
            assert!(n == accumulated_len, "advancing io slices beyond their length");
        } else {
            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")]
    #[must_use]
    #[inline]
    pub fn new(buf: &'a [u8]) -> IoSlice<'a> {
        IoSlice(sys::io::IoSlice::new(buf))
    }

    /// 前进切片的内部游标。
    ///
    /// 另请参见 [`IoSlice::advance_slices`] 以推进多个缓冲区的游标。
    ///
    ///
    /// # Panics
    ///
    /// 试图超越切片末端时出现 panic。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(io_slice_advance)]
    ///
    /// use std::io::IoSlice;
    /// use std::ops::Deref;
    ///
    /// let data = [1; 8];
    /// let mut buf = IoSlice::new(&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)
    }

    /// 在 slices 中推进一个切片。
    ///
    /// 缩小切片以删除任何完全超前的 `IoSlice`。
    /// 如果游标最终位于 `IoSlice` 的中间，则将其修改为从该游标处开始。
    ///
    /// 例如，如果我们有两个 8 字节的 `IoSlice` 的切片，并且我们提前 10 个字节，结果将只包括第二个 `IoSlice`，提前 2 个字节。
    ///
    ///
    /// # Panics
    ///
    /// 试图超越切片末端时出现 panic。
    ///
    /// # 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 take(bufs)[remove..];
        if bufs.is_empty() {
            assert!(n == accumulated_len, "advancing io slices beyond their length");
        } else {
            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()
    }
}

/// 面向字节的接收器对象的 trait。
///
/// `Write` trait 的实现者有时称为 'writers'。
///
/// Writers 由两种必需的方法 [`write`] 和 [`flush`] 定义：
///
/// * [`write`] 方法将尝试将一些数据写入对象，返回成功写入的字节数。
///
/// * [`flush`] 方法对于适配器和显式缓冲区本身很有用，以确保所有缓冲数据都已被推送到 `真正的 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 对任何包装的对象进行写操作的尝试。
    ///
    /// 不能保证对 `write` 的调用会阻塞等待数据的写入，否则可以通过 [`Err`] 变体指示被阻塞的写入。
    ///
    /// 如果返回值为 [`Ok(n)`]，则必须保证 `n <= buf.len()`。
    /// 返回值 `0` 通常意味着底层对象不再能够接受字节，并且将来也可能无法接受，或者提供的缓冲区为空。
    ///
    ///
    /// # 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 data1 = [1; 8];
    ///     let data2 = [15; 8];
    ///     let io_slice1 = IoSlice::new(&data1);
    ///     let io_slice2 = IoSlice::new(&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::const_io_error!(
                        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::const_io_error!(
                        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 Adapter<'a, T: ?Sized + 'a> {
            inner: &'a mut T,
            error: Result<()>,
        }

        impl<T: Write + ?Sized> fmt::Write for Adapter<'_, 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 = Adapter { inner: self, error: Ok(()) };
        match fmt::write(&mut output, fmt) {
            Ok(()) => Ok(()),
            Err(..) => {
                // 检查错误是否来自底层 `Write`
                if output.error.is_err() {
                    output.error
                } else {
                    Err(error::const_io_error!(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 {len} bytes long");
    ///     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 对象中进行搜索的方法。
///
/// [`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 的末尾之外进行 seek，但在字节之前进行 seek 是错误的 0.
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    End(#[stable(feature = "rust1", since = "1.0.0")] i64),

    /// 将偏移量设置为当前位置加上指定的字节数。
    ///
    /// 可以在 object 的末尾之外进行 seek，但在字节之前进行 seek 是错误的 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，它只是通知对象从 [`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` 字节)，并将它们，追加，到提供的 `String` 缓冲区。
    ///
    /// 缓冲区的先前内容将被保留。为避免，追加，到缓冲区，您需要先将其 [`clear`]。
    ///
    /// 该函数将从底层流中读取字节，直到找到换行符 (`0xA` 字节) 或 EOF。
    /// 一旦找到，直到并包括分隔符 (如果找到) 的所有字节都将被追加到 `buf`。
    ///
    /// 如果成功，此函数将返回读取的字节总数。
    ///
    /// 如果此函数返回 [`Ok(0)`]，则流已到达 EOF。
    ///
    /// 该函数正在阻塞，应谨慎使用：攻击者有可能连续发送字节而无需发送换行符或 EOF。
    ///
    /// 您可以使用 [`take`] 来限制读取的最大字节数。
    ///
    /// [`Ok(0)`]: Ok
    /// [`clear`]: String::clear
    /// [`take`]: crate::io::Read::take
    ///
    /// # 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` 中的注释。
        //
        unsafe { append_to_string(buf, |b| read_until(self, b'\n', b)) }
    }

    /// 返回对该字节 `byte` 上的 reader 拆分内容的迭代器。
    ///
    /// 这个函数返回的迭代器将返回 <code>[io::Result]<[Vec]\<u8>></code> 的实例。
    ///
    /// 返回的每个 vector 都不会在末尾有定界符字节。
    ///
    /// 只要 [`read_until`] 也产生错误，此函数就会产生错误。
    ///
    /// [io::Result]: self::Result "io::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 的各行上的迭代器。
    ///
    /// 从这个函数返回的迭代器将产生 <code>[io::Result]<[String]></code> 的实例。
    /// 返回的每个字符串末尾都不会有换行符字节 (`0xA` 字节) 或 `CRLF` (`0xD`，`0xA` 字节)。
    ///
    ///
    /// [io::Result]: self::Result "io::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)
    }
}

#[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])?;
        assert!(n as u64 <= self.limit, "number of read bytes exceeds limit");
        self.limit -= n as u64;
        Ok(n)
    }

    fn read_buf(&mut self, mut buf: BorrowedCursor<'_>) -> Result<()> {
        // 在 EOF 根本不要调用内部 reader，因为它可能仍然会阻塞
        if self.limit == 0 {
            return Ok(());
        }

        if self.limit <= buf.capacity() as u64 {
            // 如果我们只是使用 as cast 进行转换，limit 可能会环绕在 32 位目标上
            let limit = cmp::min(self.limit, usize::MAX as u64) as usize;

            let extra_init = cmp::min(limit as usize, buf.init_ref().len());

            // SAFETY: 没有将 uninit 数据写入到 ibuf
            let ibuf = unsafe { &mut buf.as_mut()[..limit] };

            let mut sliced_buf: BorrowedBuf<'_> = ibuf.into();

            // SAFETY: 已知 ibuf 的 extra_init 字节已被初始化
            unsafe {
                sliced_buf.set_init(extra_init);
            }

            let mut cursor = sliced_buf.unfilled();
            self.inner.read_buf(cursor.reborrow())?;

            let new_init = cursor.init_ref().len();
            let filled = sliced_buf.len();

            // cursor/ibuf 必须在这里丢弃

            unsafe {
                // SAFETY: 已填充的字节已被填充并因此被初始化
                buf.advance(filled);
                // SAFETY: buf 的未填充缓冲区的 new_init 字节已被初始化
                buf.set_init(new_init);
            }

            self.limit -= filled as u64;
        } else {
            let written = buf.written();
            self.inner.read_buf(buf.reborrow())?;
            self.limit -= (buf.written() - written) as u64;
        }

        Ok(())
    }
}

#[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)),
        }
    }
}