use crate::cmp;
use crate::fmt;
use crate::io::{
    self, BufRead, Initializer, IoSliceMut, Read, Seek, SeekFrom, SizeHint, DEFAULT_BUF_SIZE,
};

/// `BufReader<R>` 结构体将缓冲添加到任何 reader。
///
/// 直接使用 [`Read`] 实例可能会非常低效。
/// 例如，对 [`TcpStream`] 上 [`read`][`TcpStream::read`] 的每次调用都会导致系统调用。
/// `BufReader<R>` 对基础 [`Read`] 进行大批量的不频繁读取，并维护结果的内存缓冲区。
///
/// `BufReader<R>` 可以提高使 *小* 和 *重复* 读取对同一文件或网络套接字的调用的程序的速度。
///
/// 一次读取非常多的内容，或者仅读取一次或几次，则无济于事。
/// 从诸如 [`Vec`]`<u8>` 之类的内存中读取数据时，它也没有任何优势。
///
/// 当 `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 {} bytes long", len);
///     Ok(())
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct BufReader<R> {
    inner: R,
    buf: Box<[u8]>,
    pos: usize,
    cap: usize,
}

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> {
        unsafe {
            let mut buf = Box::new_uninit_slice(capacity).assume_init();
            inner.initializer().initialize(&mut buf);
            BufReader { inner, buf, pos: 0, cap: 0 }
        }
    }
}

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[self.pos..self.cap]
    }

    /// 返回内部缓冲区可以一次保存的字节数。
    ///
    /// # 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.len()
    }

    /// 解包此 `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.pos = 0;
        self.cap = 0;
    }
}

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.pos as u64;
        if offset < 0 {
            if let Some(new_pos) = pos.checked_sub((-offset) as u64) {
                self.pos = new_pos as usize;
                return Ok(());
            }
        } else {
            if let Some(new_pos) = pos.checked_add(offset as u64) {
                if new_pos <= self.cap as u64 {
                    self.pos = new_pos 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.pos == self.cap && buf.len() >= self.buf.len() {
            self.discard_buffer();
            return self.inner.read(buf);
        }
        let nread = {
            let mut rem = self.fill_buf()?;
            rem.read(buf)?
        };
        self.consume(nread);
        Ok(nread)
    }

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

    // 我们不能无条件地跳过，因为读取时缓冲区很大。
    unsafe fn initializer(&self) -> Initializer {
        self.inner.initializer()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<R: Read> BufRead for BufReader<R> {
    fn fill_buf(&mut self) -> io::Result<&[u8]> {
        // 如果到达内部缓冲区的末尾，则需要从基础 reader 中获取更多数据。
        //
        // 使用 `>=` 而不是更正确的 `==` 进行分支，以告知编译器 pos..cap 切片始终有效。
        //
        if self.pos >= self.cap {
            debug_assert!(self.pos == self.cap);
            self.cap = self.inner.read(&mut self.buf)?;
            self.pos = 0;
        }
        Ok(&self.buf[self.pos..self.cap])
    }

    fn consume(&mut self, amt: usize) {
        self.pos = cmp::min(self.pos + amt, self.cap);
    }
}

#[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.cap - self.pos, self.buf.len()))
            .finish()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<R: Seek> Seek for BufReader<R> {
    /// 在基础 reader 中寻找以字节为单位的偏移量。
    ///
    /// 用于 [`SeekFrom::Current`]`(_)` 的搜索位置是 `BufReader<R>` 没有内部缓冲区时基础 reader 所在的位置。
    ///
    /// 搜寻总是会丢弃内部缓冲区，即使寻找位置本来会落在内部缓冲区内。
    /// 这保证了在寻道之后立即调用 [`BufReader::into_inner()`] 会在相同位置产生基础 reader。
    ///
    /// 要查找而不丢弃内部缓冲区，请使用 [`BufReader::seek_relative`]。
    ///
    /// 有关更多详细信息，请参见 [`std::io::Seek`]。
    ///
    /// Note: 在使用 [`SeekFrom::Current`]`(n)` 进行搜索的 edge 情况下，`n` 减去内部缓冲区长度使 `i64` 溢出，将执行两次搜索，而不是一次。
    ///
    /// 如果第二个搜索返回 [`Err`]，则底层的 reader 将保留在与 [`SeekFrom::Current`]`(0)` 一起调用 `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.cap - self.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.cap - self.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))
    }
}