mod buffer;

use crate::fmt;
use crate::io::{
    self, BorrowedCursor, BufRead, IoSliceMut, Read, Seek, SeekFrom, SizeHint, DEFAULT_BUF_SIZE,
};
use buffer::Buffer;

/// `BufReader<R>` 结构体将缓冲添加到任何 reader。
///
/// 直接使用 [`Read`] 实例可能会非常低效。
/// 例如，对 [`TcpStream`] 上 [`read`][`TcpStream::read`] 的每次调用都会导致系统调用。
/// `BufReader<R>` 对底层 [`Read`] 进行大批量的不频繁读取，并维护结果的内存缓冲区。
///
/// `BufReader<R>` 可以提高对同一文件或网络套接字进行小规模重复读取调用的程序的速度。
///
/// 一次读取非常多的内容，或者仅读取一次或几次，则无济于事。
/// 从已经在内存中的源读取时，它也没有任何优势，例如 <code>[Vec]\<u8></code>.
///
/// 当 `BufReader<R>` 被丢弃时，其缓冲区的内容将被丢弃。
/// 在同一流上创建 `BufReader<R>` 的多个实例可能会导致数据丢失。
/// 将 `BufReader<R>` 与 [`BufReader::into_inner`] 展开包装后，从底层 reader 进行读取也会导致数据丢失。
///
///
///
///
///
// HACK(#78696): 不能将 `crate` 用于关联的项
/// [`TcpStream::read`]: super::super::super::net::TcpStream::read
/// [`TcpStream`]: crate::net::TcpStream
///
/// # Examples
///
/// ```no_run
/// use std::io::prelude::*;
/// use std::io::BufReader;
/// use std::fs::File;
///
/// fn main() -> std::io::Result<()> {
///     let f = File::open("log.txt")?;
///     let mut reader = BufReader::new(f);
///
///     let mut line = String::new();
///     let len = reader.read_line(&mut line)?;
///     println!("First line is {len} bytes long");
///     Ok(())
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct BufReader<R> {
    inner: R,
    buf: Buffer,
}

impl<R: Read> BufReader<R> {
    /// 创建一个具有默认缓冲区容量的新 `BufReader<R>`。
    /// 当前默认值为 8 KB，但可能会在 future 中进行更改。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::BufReader;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f = File::open("log.txt")?;
    ///     let reader = BufReader::new(f);
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn new(inner: R) -> BufReader<R> {
        BufReader::with_capacity(DEFAULT_BUF_SIZE, inner)
    }

    /// 用指定的缓冲区容量创建一个新的 `BufReader<R>`。
    ///
    /// # Examples
    ///
    /// 创建一个具有十个字节容量的缓冲区：
    ///
    /// ```no_run
    /// use std::io::BufReader;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f = File::open("log.txt")?;
    ///     let reader = BufReader::with_capacity(10, f);
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn with_capacity(capacity: usize, inner: R) -> BufReader<R> {
        BufReader { inner, buf: Buffer::with_capacity(capacity) }
    }
}

impl<R> BufReader<R> {
    /// 获取对底层 reader 的引用。
    ///
    /// 直接从底层 reader 读取是不可取的。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::BufReader;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f1 = File::open("log.txt")?;
    ///     let reader = BufReader::new(f1);
    ///
    ///     let f2 = reader.get_ref();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn get_ref(&self) -> &R {
        &self.inner
    }

    /// 获取底层 reader 的可变引用。
    ///
    /// 直接从底层 reader 读取是不可取的。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::BufReader;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f1 = File::open("log.txt")?;
    ///     let mut reader = BufReader::new(f1);
    ///
    ///     let f2 = reader.get_mut();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn get_mut(&mut self) -> &mut R {
        &mut self.inner
    }

    /// 返回对内部缓冲数据的引用。
    ///
    /// 与 [`fill_buf`] 不同，如果缓冲区为空，它将不会尝试填充缓冲区。
    ///
    /// [`fill_buf`]: BufRead::fill_buf
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::{BufReader, BufRead};
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f = File::open("log.txt")?;
    ///     let mut reader = BufReader::new(f);
    ///     assert!(reader.buffer().is_empty());
    ///
    ///     if reader.fill_buf()?.len() > 0 {
    ///         assert!(!reader.buffer().is_empty());
    ///     }
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "bufreader_buffer", since = "1.37.0")]
    pub fn buffer(&self) -> &[u8] {
        self.buf.buffer()
    }

    /// 返回内部缓冲区可以一次保存的字节数。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::{BufReader, BufRead};
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f = File::open("log.txt")?;
    ///     let mut reader = BufReader::new(f);
    ///
    ///     let capacity = reader.capacity();
    ///     let buffer = reader.fill_buf()?;
    ///     assert!(buffer.len() <= capacity);
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "buffered_io_capacity", since = "1.46.0")]
    pub fn capacity(&self) -> usize {
        self.buf.capacity()
    }

    /// 解包此 `BufReader<R>`，返回底层 reader。
    ///
    /// 请注意，内部缓冲区中的所有剩余数据都会丢失。
    /// 因此，从底层 reader 进行后续读取可能会导致数据丢失。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::io::BufReader;
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f1 = File::open("log.txt")?;
    ///     let reader = BufReader::new(f1);
    ///
    ///     let f2 = reader.into_inner();
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn into_inner(self) -> R {
        self.inner
    }

    /// 使内部缓冲区中的所有数据无效。
    #[inline]
    fn discard_buffer(&mut self) {
        self.buf.discard_buffer()
    }
}

// 这仅由断言初始化跟踪正确的测试使用。
#[cfg(test)]
impl<R> BufReader<R> {
    pub fn initialized(&self) -> usize {
        self.buf.initialized()
    }
}

impl<R: Seek> BufReader<R> {
    /// 相对于当前位置寻找。
    /// 如果新位置位于缓冲区内，则不会刷新缓冲区，从而实现更有效的查找。
    /// 此方法不返回底层 reader 的位置，因此如果需要，调用者必须自己跟踪此信息。
    ///
    #[stable(feature = "bufreader_seek_relative", since = "1.53.0")]
    pub fn seek_relative(&mut self, offset: i64) -> io::Result<()> {
        let pos = self.buf.pos() as u64;
        if offset < 0 {
            if let Some(_) = pos.checked_sub((-offset) as u64) {
                self.buf.unconsume((-offset) as usize);
                return Ok(());
            }
        } else if let Some(new_pos) = pos.checked_add(offset as u64) {
            if new_pos <= self.buf.filled() as u64 {
                self.buf.consume(offset as usize);
                return Ok(());
            }
        }

        self.seek(SeekFrom::Current(offset)).map(drop)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<R: Read> Read for BufReader<R> {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        // 如果我们没有任何缓冲数据，并且正在进行大量读取 (大于内部缓冲区)，请完全绕过内部缓冲区。
        //
        //
        if self.buf.pos() == self.buf.filled() && buf.len() >= self.capacity() {
            self.discard_buffer();
            return self.inner.read(buf);
        }
        let nread = {
            let mut rem = self.fill_buf()?;
            rem.read(buf)?
        };
        self.consume(nread);
        Ok(nread)
    }

    fn read_buf(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> {
        // 如果我们没有任何缓冲数据，并且正在进行大量读取 (大于内部缓冲区)，请完全绕过内部缓冲区。
        //
        //
        if self.buf.pos() == self.buf.filled() && cursor.capacity() >= self.capacity() {
            self.discard_buffer();
            return self.inner.read_buf(cursor);
        }

        let prev = cursor.written();

        let mut rem = self.fill_buf()?;
        rem.read_buf(cursor.reborrow())?;

        self.consume(cursor.written() - prev); // 已知 read_buf 的切片实现从不填充 buf

        Ok(())
    }

    // 与反序列化器一起使用时，来自 BufReader 的小 read_exacts 非常普遍。
    // 默认实现在循环中调用 read，这会导致在公共路径中缓冲区具有足够的字节来填充传入缓冲区的公共路径，导致代码生成异常差。
    //
    //
    fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
        if self.buf.consume_with(buf.len(), |claimed| buf.copy_from_slice(claimed)) {
            return Ok(());
        }

        crate::io::default_read_exact(self, buf)
    }

    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
        let total_len = bufs.iter().map(|b| b.len()).sum::<usize>();
        if self.buf.pos() == self.buf.filled() && total_len >= self.capacity() {
            self.discard_buffer();
            return self.inner.read_vectored(bufs);
        }
        let nread = {
            let mut rem = self.fill_buf()?;
            rem.read_vectored(bufs)?
        };
        self.consume(nread);
        Ok(nread)
    }

    fn is_read_vectored(&self) -> bool {
        self.inner.is_read_vectored()
    }

    // 内部 reader 可能具有优化的 `read_to_end`。
    // 耗尽我们的缓冲区，然后委托给内部实现。
    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
        let inner_buf = self.buffer();
        buf.extend_from_slice(inner_buf);
        let nread = inner_buf.len();
        self.discard_buffer();
        Ok(nread + self.inner.read_to_end(buf)?)
    }

    // 内部 reader 可能具有优化的 `read_to_end`。
    // 耗尽我们的缓冲区，然后委托给内部实现。
    fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
        // 在下面的一般 `else` 情况下，我们必须将字节读入一个 side 缓冲区，检查它们是否是有效的 UTF-8，然后将它们追加到 `buf`。
        // 这需要一个潜在的大型 memcpy。
        //
        // 如果 `buf` 为空 -- 最常见的情况 -- 我们可以利用 `append_to_string` 直接读入 `buf` 的内部字节缓冲区，从而保存分配和 memcpy。
        //
        //
        //
        if buf.is_empty() {
            // `append_to_string` 的安全性仅依赖于被追加到的缓冲区，因为它只检查新数据的 UTF-8 有效性。如果 `buf` 中存在现有内容，那么不可信的 reader (即 `self.inner`) 不仅可以追加字节，还可以修改现有字节并使它们无效。
            //
            // 另一方面，如果 `buf` 为空，则根据定义，任何写入都必须追加，并且 `append_to_string` 将验证所有新字节。
            //
            //
            //
            unsafe { crate::io::append_to_string(buf, |b| self.read_to_end(b)) }
        } else {
            // 我们不能将字节缓冲区直接追加到 `buf` 字符串上，因为可能存在仅部分读取的不完整 UTF-8 序列。
            // 我们必须首先将所有内容读入 side 缓冲区，然后在整个缓冲区上调用 `from_utf8`。
            //
            //
            let mut bytes = Vec::new();
            self.read_to_end(&mut bytes)?;
            let string = crate::str::from_utf8(&bytes).map_err(|_| {
                io::const_io_error!(
                    io::ErrorKind::InvalidData,
                    "stream did not contain valid UTF-8",
                )
            })?;
            *buf += string;
            Ok(string.len())
        }
    }
}

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

    fn consume(&mut self, amt: usize) {
        self.buf.consume(amt)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<R> fmt::Debug for BufReader<R>
where
    R: fmt::Debug,
{
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_struct("BufReader")
            .field("reader", &self.inner)
            .field(
                "buffer",
                &format_args!("{}/{}", self.buf.filled() - self.buf.pos(), self.capacity()),
            )
            .finish()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<R: Seek> Seek for BufReader<R> {
    /// 在底层 reader 中查找偏移量 (以字节为单位)。
    ///
    /// 用于使用 <code>[SeekFrom::Current]\(_)</code> 查找的位置是底层 reader 所在的位置，如果 `BufReader<R>` 没有内部缓冲区。
    ///
    /// 查找总是会丢弃内部缓冲区，即使查找位置本来会落在内部缓冲区内。
    /// 这保证了在查找之后立即调用 [`BufReader::into_inner()`] 会在相同位置产生底层 reader。
    ///
    /// 要在不丢弃内部缓冲区的情况下进行查找，请使用 [`BufReader::seek_relative`]。
    ///
    /// 有关更多详细信息，请参见 [`std::io::Seek`]。
    ///
    /// Note: 在 edge 情况下，您使用 <code>[SeekFrom::Current]\(n)</code> 进行查找，其中 `n` 减去内部缓冲区长度会溢出 `i64`，将执行两次查找而不是一次查找。
    ///
    /// 如果第二个 seek 返回 [`Err`]，则底层 reader 将保留在与使用 <code>[SeekFrom::Current]\(0)</code> 调用 `seek` 时相同的位置。
    ///
    /// [`std::io::Seek`]: Seek
    ///
    ///
    ///
    ///
    ///
    ///
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        let result: u64;
        if let SeekFrom::Current(n) = pos {
            let remainder = (self.buf.filled() - self.buf.pos()) as i64;
            // 可以放心地认为其余部分适合 i64，因为这意味着我们设法分配了 8 EB，这是荒谬的。
            // 但是，对于一些奇怪的底层 reader 来说，支持 i64::MIN 的搜索并非不可能，所以我们需要在减去余数时处理下溢。
            //
            //
            //
            if let Some(offset) = n.checked_sub(remainder) {
                result = self.inner.seek(SeekFrom::Current(offset))?;
            } else {
                // 向后搜索我们的余数，然后通过偏移量
                self.inner.seek(SeekFrom::Current(-remainder))?;
                self.discard_buffer();
                result = self.inner.seek(SeekFrom::Current(n))?;
            }
        } else {
            // 使用 Start/End 查找并不关心我们的缓冲区长度。
            result = self.inner.seek(pos)?;
        }
        self.discard_buffer();
        Ok(result)
    }

    /// 从流的开头返回当前查找位置。
    ///
    /// 返回的值等效于 `self.seek(SeekFrom::Current(0))`，但不刷新内部缓冲区。
    /// 由于进行了这种优化，该函数不能保证在此之后立即调用 `.into_inner()` 将在同一位置产生底层 reader。
    /// 如果需要该保证，请改用 [`BufReader::seek`]。
    ///
    /// # Panics
    ///
    /// 如果内部 reader 的位置小于缓冲数据量，则此函数将为 panic。
    /// 如果内部 reader 的 [`Seek::stream_position`] 实现不正确，或者由于直接在底层 reader 上调用 [`Seek::seek`] 而导致位置不同步，则可能发生这种情况。
    ///
    ///
    /// # 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(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    fn stream_position(&mut self) -> io::Result<u64> {
        let remainder = (self.buf.filled() - self.buf.pos()) as u64;
        self.inner.stream_position().map(|pos| {
            pos.checked_sub(remainder).expect(
                "overflow when subtracting remaining buffer size from inner stream position",
            )
        })
    }
}

impl<T> SizeHint for BufReader<T> {
    #[inline]
    fn lower_bound(&self) -> usize {
        SizeHint::lower_bound(self.get_ref()) + self.buffer().len()
    }

    #[inline]
    fn upper_bound(&self) -> Option<usize> {
        SizeHint::upper_bound(self.get_ref()).and_then(|up| self.buffer().len().checked_add(up))
    }
}