| mod buffer; |
| |
| use crate::fmt; |
| use crate::io::{ |
| self, BorrowedCursor, BufRead, IoSliceMut, Read, Seek, SeekFrom, SizeHint, DEFAULT_BUF_SIZE, |
| }; |
| use buffer::Buffer; |
| |
| /// The `BufReader<R>` struct adds buffering to any reader. |
| /// |
| /// It can be excessively inefficient to work directly with a [`Read`] instance. |
| /// For example, every call to [`read`][`TcpStream::read`] on [`TcpStream`] |
| /// results in a system call. A `BufReader<R>` performs large, infrequent reads on |
| /// the underlying [`Read`] and maintains an in-memory buffer of the results. |
| /// |
| /// `BufReader<R>` can improve the speed of programs that make *small* and |
| /// *repeated* read calls to the same file or network socket. It does not |
| /// help when reading very large amounts at once, or reading just one or a few |
| /// times. It also provides no advantage when reading from a source that is |
| /// already in memory, like a <code>[Vec]\<u8></code>. |
| /// |
| /// When the `BufReader<R>` is dropped, the contents of its buffer will be |
| /// discarded. Creating multiple instances of a `BufReader<R>` on the same |
| /// stream can cause data loss. Reading from the underlying reader after |
| /// unwrapping the `BufReader<R>` with [`BufReader::into_inner`] can also cause |
| /// data loss. |
| /// |
| // HACK(#78696): can't use `crate` for associated items |
| /// [`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> { |
| /// Creates a new `BufReader<R>` with a default buffer capacity. The default is currently 8 KB, |
| /// but may change in the 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) |
| } |
| |
| /// Creates a new `BufReader<R>` with the specified buffer capacity. |
| /// |
| /// # Examples |
| /// |
| /// Creating a buffer with ten bytes of capacity: |
| /// |
| /// ```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> { |
| /// Gets a reference to the underlying reader. |
| /// |
| /// It is inadvisable to directly read from the underlying 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 |
| } |
| |
| /// Gets a mutable reference to the underlying reader. |
| /// |
| /// It is inadvisable to directly read from the underlying 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 |
| } |
| |
| /// Returns a reference to the internally buffered data. |
| /// |
| /// Unlike [`fill_buf`], this will not attempt to fill the buffer if it is empty. |
| /// |
| /// [`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() |
| } |
| |
| /// Returns the number of bytes the internal buffer can hold at once. |
| /// |
| /// # 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() |
| } |
| |
| /// Unwraps this `BufReader<R>`, returning the underlying reader. |
| /// |
| /// Note that any leftover data in the internal buffer is lost. Therefore, |
| /// a following read from the underlying reader may lead to data loss. |
| /// |
| /// # 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 |
| } |
| |
| /// Invalidates all data in the internal buffer. |
| #[inline] |
| fn discard_buffer(&mut self) { |
| self.buf.discard_buffer() |
| } |
| } |
| |
| // This is only used by a test which asserts that the initialization-tracking is correct. |
| #[cfg(test)] |
| impl<R> BufReader<R> { |
| pub fn initialized(&self) -> usize { |
| self.buf.initialized() |
| } |
| } |
| |
| impl<R: Seek> BufReader<R> { |
| /// Seeks relative to the current position. If the new position lies within the buffer, |
| /// the buffer will not be flushed, allowing for more efficient seeks. |
| /// This method does not return the location of the underlying reader, so the caller |
| /// must track this information themselves if it is required. |
| #[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 we don't have any buffered data and we're doing a massive read |
| // (larger than our internal buffer), bypass our internal buffer |
| // entirely. |
| 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 we don't have any buffered data and we're doing a massive read |
| // (larger than our internal buffer), bypass our internal buffer |
| // entirely. |
| 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); //slice impl of read_buf known to never unfill buf |
| |
| Ok(()) |
| } |
| |
| // Small read_exacts from a BufReader are extremely common when used with a deserializer. |
| // The default implementation calls read in a loop, which results in surprisingly poor code |
| // generation for the common path where the buffer has enough bytes to fill the passed-in |
| // buffer. |
| 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() |
| } |
| |
| // The inner reader might have an optimized `read_to_end`. Drain our buffer and then |
| // delegate to the inner implementation. |
| 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)?) |
| } |
| |
| // The inner reader might have an optimized `read_to_end`. Drain our buffer and then |
| // delegate to the inner implementation. |
| fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> { |
| // In the general `else` case below we must read bytes into a side buffer, check |
| // that they are valid UTF-8, and then append them to `buf`. This requires a |
| // potentially large memcpy. |
| // |
| // If `buf` is empty--the most common case--we can leverage `append_to_string` |
| // to read directly into `buf`'s internal byte buffer, saving an allocation and |
| // a memcpy. |
| if buf.is_empty() { |
| // `append_to_string`'s safety relies on the buffer only being appended to since |
| // it only checks the UTF-8 validity of new data. If there were existing content in |
| // `buf` then an untrustworthy reader (i.e. `self.inner`) could not only append |
| // bytes but also modify existing bytes and render them invalid. On the other hand, |
| // if `buf` is empty then by definition any writes must be appends and |
| // `append_to_string` will validate all of the new bytes. |
| unsafe { crate::io::append_to_string(buf, |b| self.read_to_end(b)) } |
| } else { |
| // We cannot append our byte buffer directly onto the `buf` String as there could |
| // be an incomplete UTF-8 sequence that has only been partially read. We must read |
| // everything into a side buffer first and then call `from_utf8` on the complete |
| // buffer. |
| 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> { |
| /// Seek to an offset, in bytes, in the underlying reader. |
| /// |
| /// The position used for seeking with <code>[SeekFrom::Current]\(_)</code> is the |
| /// position the underlying reader would be at if the `BufReader<R>` had no |
| /// internal buffer. |
| /// |
| /// Seeking always discards the internal buffer, even if the seek position |
| /// would otherwise fall within it. This guarantees that calling |
| /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader |
| /// at the same position. |
| /// |
| /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`]. |
| /// |
| /// See [`std::io::Seek`] for more details. |
| /// |
| /// Note: In the edge case where you're seeking with <code>[SeekFrom::Current]\(n)</code> |
| /// where `n` minus the internal buffer length overflows an `i64`, two |
| /// seeks will be performed instead of one. If the second seek returns |
| /// [`Err`], the underlying reader will be left at the same position it would |
| /// have if you called `seek` with <code>[SeekFrom::Current]\(0)</code>. |
| /// |
| /// [`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; |
| // it should be safe to assume that remainder fits within an i64 as the alternative |
| // means we managed to allocate 8 exbibytes and that's absurd. |
| // But it's not out of the realm of possibility for some weird underlying reader to |
| // support seeking by i64::MIN so we need to handle underflow when subtracting |
| // remainder. |
| if let Some(offset) = n.checked_sub(remainder) { |
| result = self.inner.seek(SeekFrom::Current(offset))?; |
| } else { |
| // seek backwards by our remainder, and then by the offset |
| self.inner.seek(SeekFrom::Current(-remainder))?; |
| self.discard_buffer(); |
| result = self.inner.seek(SeekFrom::Current(n))?; |
| } |
| } else { |
| // Seeking with Start/End doesn't care about our buffer length. |
| result = self.inner.seek(pos)?; |
| } |
| self.discard_buffer(); |
| Ok(result) |
| } |
| |
| /// Returns the current seek position from the start of the stream. |
| /// |
| /// The value returned is equivalent to `self.seek(SeekFrom::Current(0))` |
| /// but does not flush the internal buffer. Due to this optimization the |
| /// function does not guarantee that calling `.into_inner()` immediately |
| /// afterwards will yield the underlying reader at the same position. Use |
| /// [`BufReader::seek`] instead if you require that guarantee. |
| /// |
| /// # Panics |
| /// |
| /// This function will panic if the position of the inner reader is smaller |
| /// than the amount of buffered data. That can happen if the inner reader |
| /// has an incorrect implementation of [`Seek::stream_position`], or if the |
| /// position has gone out of sync due to calling [`Seek::seek`] directly on |
| /// the underlying reader. |
| /// |
| /// # 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)) |
| } |
| } |
