library/std/src/io/buffered/bufreader.rs

   1 mod buffer;
   2
   3 use crate::fmt;
   4 use crate::io::{
   5     self, BorrowedCursor, BufRead, IoSliceMut, Read, Seek, SeekFrom, SizeHint, DEFAULT_BUF_SIZE,
   6 };
   7 use buffer::Buffer;
   8
   9 /// The `BufReader<R>` struct adds buffering to any reader.
  10 ///
  11 /// It can be excessively inefficient to work directly with a [`Read`] instance.
  12 /// For example, every call to [`read`][`TcpStream::read`] on [`TcpStream`]
  13 /// results in a system call. A `BufReader<R>` performs large, infrequent reads on
  14 /// the underlying [`Read`] and maintains an in-memory buffer of the results.
  15 ///
  16 /// `BufReader<R>` can improve the speed of programs that make *small* and
  17 /// *repeated* read calls to the same file or network socket. It does not
  18 /// help when reading very large amounts at once, or reading just one or a few
  19 /// times. It also provides no advantage when reading from a source that is
  20 /// already in memory, like a <code>[Vec]\<u8></code>.
  21 ///
  22 /// When the `BufReader<R>` is dropped, the contents of its buffer will be
  23 /// discarded. Creating multiple instances of a `BufReader<R>` on the same
  24 /// stream can cause data loss. Reading from the underlying reader after
  25 /// unwrapping the `BufReader<R>` with [`BufReader::into_inner`] can also cause
  26 /// data loss.
  27 ///
  28 // HACK(#78696): can't use `crate` for associated items
  29 /// [`TcpStream::read`]: super::super::super::net::TcpStream::read
  30 /// [`TcpStream`]: crate::net::TcpStream
  31 ///
  32 /// # Examples
  33 ///
  34 /// ```no_run
  35 /// use std::io::prelude::*;
  36 /// use std::io::BufReader;
  37 /// use std::fs::File;
  38 ///
  39 /// fn main() -> std::io::Result<()> {
  40 ///     let f = File::open("log.txt")?;
  41 ///     let mut reader = BufReader::new(f);
  42 ///
  43 ///     let mut line = String::new();
  44 ///     let len = reader.read_line(&mut line)?;
  45 ///     println!("First line is {len} bytes long");
  46 ///     Ok(())
  47 /// }
  48 /// ```
  49 #[stable(feature = "rust1", since = "1.0.0")]
  50 pub struct BufReader<R> {
  51     inner: R,
  52     buf: Buffer,
  53 }
  54
  55 impl<R: Read> BufReader<R> {
  56     /// Creates a new `BufReader<R>` with a default buffer capacity. The default is currently 8 KB,
  57     /// but may change in the future.
  58     ///
  59     /// # Examples
  60     ///
  61     /// ```no_run
  62     /// use std::io::BufReader;
  63     /// use std::fs::File;
  64     ///
  65     /// fn main() -> std::io::Result<()> {
  66     ///     let f = File::open("log.txt")?;
  67     ///     let reader = BufReader::new(f);
  68     ///     Ok(())
  69     /// }
  70     /// ```
  71     #[stable(feature = "rust1", since = "1.0.0")]
  72     pub fn new(inner: R) -> BufReader<R> {
  73         BufReader::with_capacity(DEFAULT_BUF_SIZE, inner)
  74     }
  75
  76     /// Creates a new `BufReader<R>` with the specified buffer capacity.
  77     ///
  78     /// # Examples
  79     ///
  80     /// Creating a buffer with ten bytes of capacity:
  81     ///
  82     /// ```no_run
  83     /// use std::io::BufReader;
  84     /// use std::fs::File;
  85     ///
  86     /// fn main() -> std::io::Result<()> {
  87     ///     let f = File::open("log.txt")?;
  88     ///     let reader = BufReader::with_capacity(10, f);
  89     ///     Ok(())
  90     /// }
  91     /// ```
  92     #[stable(feature = "rust1", since = "1.0.0")]
  93     pub fn with_capacity(capacity: usize, inner: R) -> BufReader<R> {
  94         BufReader { inner, buf: Buffer::with_capacity(capacity) }
  95     }
  96 }
  97
  98 impl<R> BufReader<R> {
  99     /// Gets a reference to the underlying reader.
 100     ///
 101     /// It is inadvisable to directly read from the underlying reader.
 102     ///
 103     /// # Examples
 104     ///
 105     /// ```no_run
 106     /// use std::io::BufReader;
 107     /// use std::fs::File;
 108     ///
 109     /// fn main() -> std::io::Result<()> {
 110     ///     let f1 = File::open("log.txt")?;
 111     ///     let reader = BufReader::new(f1);
 112     ///
 113     ///     let f2 = reader.get_ref();
 114     ///     Ok(())
 115     /// }
 116     /// ```
 117     #[stable(feature = "rust1", since = "1.0.0")]
 118     pub fn get_ref(&self) -> &R {
 119         &self.inner
 120     }
 121
 122     /// Gets a mutable reference to the underlying reader.
 123     ///
 124     /// It is inadvisable to directly read from the underlying reader.
 125     ///
 126     /// # Examples
 127     ///
 128     /// ```no_run
 129     /// use std::io::BufReader;
 130     /// use std::fs::File;
 131     ///
 132     /// fn main() -> std::io::Result<()> {
 133     ///     let f1 = File::open("log.txt")?;
 134     ///     let mut reader = BufReader::new(f1);
 135     ///
 136     ///     let f2 = reader.get_mut();
 137     ///     Ok(())
 138     /// }
 139     /// ```
 140     #[stable(feature = "rust1", since = "1.0.0")]
 141     pub fn get_mut(&mut self) -> &mut R {
 142         &mut self.inner
 143     }
 144
 145     /// Returns a reference to the internally buffered data.
 146     ///
 147     /// Unlike [`fill_buf`], this will not attempt to fill the buffer if it is empty.
 148     ///
 149     /// [`fill_buf`]: BufRead::fill_buf
 150     ///
 151     /// # Examples
 152     ///
 153     /// ```no_run
 154     /// use std::io::{BufReader, BufRead};
 155     /// use std::fs::File;
 156     ///
 157     /// fn main() -> std::io::Result<()> {
 158     ///     let f = File::open("log.txt")?;
 159     ///     let mut reader = BufReader::new(f);
 160     ///     assert!(reader.buffer().is_empty());
 161     ///
 162     ///     if reader.fill_buf()?.len() > 0 {
 163     ///         assert!(!reader.buffer().is_empty());
 164     ///     }
 165     ///     Ok(())
 166     /// }
 167     /// ```
 168     #[stable(feature = "bufreader_buffer", since = "1.37.0")]
 169     pub fn buffer(&self) -> &[u8] {
 170         self.buf.buffer()
 171     }
 172
 173     /// Returns the number of bytes the internal buffer can hold at once.
 174     ///
 175     /// # Examples
 176     ///
 177     /// ```no_run
 178     /// use std::io::{BufReader, BufRead};
 179     /// use std::fs::File;
 180     ///
 181     /// fn main() -> std::io::Result<()> {
 182     ///     let f = File::open("log.txt")?;
 183     ///     let mut reader = BufReader::new(f);
 184     ///
 185     ///     let capacity = reader.capacity();
 186     ///     let buffer = reader.fill_buf()?;
 187     ///     assert!(buffer.len() <= capacity);
 188     ///     Ok(())
 189     /// }
 190     /// ```
 191     #[stable(feature = "buffered_io_capacity", since = "1.46.0")]
 192     pub fn capacity(&self) -> usize {
 193         self.buf.capacity()
 194     }
 195
 196     /// Unwraps this `BufReader<R>`, returning the underlying reader.
 197     ///
 198     /// Note that any leftover data in the internal buffer is lost. Therefore,
 199     /// a following read from the underlying reader may lead to data loss.
 200     ///
 201     /// # Examples
 202     ///
 203     /// ```no_run
 204     /// use std::io::BufReader;
 205     /// use std::fs::File;
 206     ///
 207     /// fn main() -> std::io::Result<()> {
 208     ///     let f1 = File::open("log.txt")?;
 209     ///     let reader = BufReader::new(f1);
 210     ///
 211     ///     let f2 = reader.into_inner();
 212     ///     Ok(())
 213     /// }
 214     /// ```
 215     #[stable(feature = "rust1", since = "1.0.0")]
 216     pub fn into_inner(self) -> R {
 217         self.inner
 218     }
 219
 220     /// Invalidates all data in the internal buffer.
 221     #[inline]
 222     fn discard_buffer(&mut self) {
 223         self.buf.discard_buffer()
 224     }
 225 }
 226
 227 // This is only used by a test which asserts that the initialization-tracking is correct.
 228 #[cfg(test)]
 229 impl<R> BufReader<R> {
 230     pub fn initialized(&self) -> usize {
 231         self.buf.initialized()
 232     }
 233 }
 234
 235 impl<R: Seek> BufReader<R> {
 236     /// Seeks relative to the current position. If the new position lies within the buffer,
 237     /// the buffer will not be flushed, allowing for more efficient seeks.
 238     /// This method does not return the location of the underlying reader, so the caller
 239     /// must track this information themselves if it is required.
 240     #[stable(feature = "bufreader_seek_relative", since = "1.53.0")]
 241     pub fn seek_relative(&mut self, offset: i64) -> io::Result<()> {
 242         let pos = self.buf.pos() as u64;
 243         if offset < 0 {
 244             if let Some(_) = pos.checked_sub((-offset) as u64) {
 245                 self.buf.unconsume((-offset) as usize);
 246                 return Ok(());
 247             }
 248         } else if let Some(new_pos) = pos.checked_add(offset as u64) {
 249             if new_pos <= self.buf.filled() as u64 {
 250                 self.buf.consume(offset as usize);
 251                 return Ok(());
 252             }
 253         }
 254
 255         self.seek(SeekFrom::Current(offset)).map(drop)
 256     }
 257 }
 258
 259 #[stable(feature = "rust1", since = "1.0.0")]
 260 impl<R: Read> Read for BufReader<R> {
 261     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 262         // If we don't have any buffered data and we're doing a massive read
 263         // (larger than our internal buffer), bypass our internal buffer
 264         // entirely.
 265         if self.buf.pos() == self.buf.filled() && buf.len() >= self.capacity() {
 266             self.discard_buffer();
 267             return self.inner.read(buf);
 268         }
 269         let nread = {
 270             let mut rem = self.fill_buf()?;
 271             rem.read(buf)?
 272         };
 273         self.consume(nread);
 274         Ok(nread)
 275     }
 276
 277     fn read_buf(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> {
 278         // If we don't have any buffered data and we're doing a massive read
 279         // (larger than our internal buffer), bypass our internal buffer
 280         // entirely.
 281         if self.buf.pos() == self.buf.filled() && cursor.capacity() >= self.capacity() {
 282             self.discard_buffer();
 283             return self.inner.read_buf(cursor);
 284         }
 285
 286         let prev = cursor.written();
 287
 288         let mut rem = self.fill_buf()?;
 289         rem.read_buf(cursor.reborrow())?;
 290
 291         self.consume(cursor.written() - prev); //slice impl of read_buf known to never unfill buf
 292
 293         Ok(())
 294     }
 295
 296     // Small read_exacts from a BufReader are extremely common when used with a deserializer.
 297     // The default implementation calls read in a loop, which results in surprisingly poor code
 298     // generation for the common path where the buffer has enough bytes to fill the passed-in
 299     // buffer.
 300     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
 301         if self.buf.consume_with(buf.len(), |claimed| buf.copy_from_slice(claimed)) {
 302             return Ok(());
 303         }
 304
 305         crate::io::default_read_exact(self, buf)
 306     }
 307
 308     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 309         let total_len = bufs.iter().map(|b| b.len()).sum::<usize>();
 310         if self.buf.pos() == self.buf.filled() && total_len >= self.capacity() {
 311             self.discard_buffer();
 312             return self.inner.read_vectored(bufs);
 313         }
 314         let nread = {
 315             let mut rem = self.fill_buf()?;
 316             rem.read_vectored(bufs)?
 317         };
 318         self.consume(nread);
 319         Ok(nread)
 320     }
 321
 322     fn is_read_vectored(&self) -> bool {
 323         self.inner.is_read_vectored()
 324     }
 325
 326     // The inner reader might have an optimized `read_to_end`. Drain our buffer and then
 327     // delegate to the inner implementation.
 328     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
 329         let inner_buf = self.buffer();
 330         buf.extend_from_slice(inner_buf);
 331         let nread = inner_buf.len();
 332         self.discard_buffer();
 333         Ok(nread + self.inner.read_to_end(buf)?)
 334     }
 335
 336     // The inner reader might have an optimized `read_to_end`. Drain our buffer and then
 337     // delegate to the inner implementation.
 338     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
 339         // In the general `else` case below we must read bytes into a side buffer, check
 340         // that they are valid UTF-8, and then append them to `buf`. This requires a
 341         // potentially large memcpy.
 342         //
 343         // If `buf` is empty--the most common case--we can leverage `append_to_string`
 344         // to read directly into `buf`'s internal byte buffer, saving an allocation and
 345         // a memcpy.
 346         if buf.is_empty() {
 347             // `append_to_string`'s safety relies on the buffer only being appended to since
 348             // it only checks the UTF-8 validity of new data. If there were existing content in
 349             // `buf` then an untrustworthy reader (i.e. `self.inner`) could not only append
 350             // bytes but also modify existing bytes and render them invalid. On the other hand,
 351             // if `buf` is empty then by definition any writes must be appends and
 352             // `append_to_string` will validate all of the new bytes.
 353             unsafe { crate::io::append_to_string(buf, |b| self.read_to_end(b)) }
 354         } else {
 355             // We cannot append our byte buffer directly onto the `buf` String as there could
 356             // be an incomplete UTF-8 sequence that has only been partially read. We must read
 357             // everything into a side buffer first and then call `from_utf8` on the complete
 358             // buffer.
 359             let mut bytes = Vec::new();
 360             self.read_to_end(&mut bytes)?;
 361             let string = crate::str::from_utf8(&bytes).map_err(|_| {
 362                 io::const_io_error!(
 363                     io::ErrorKind::InvalidData,
 364                     "stream did not contain valid UTF-8",
 365                 )
 366             })?;
 367             *buf += string;
 368             Ok(string.len())
 369         }
 370     }
 371 }
 372
 373 #[stable(feature = "rust1", since = "1.0.0")]
 374 impl<R: Read> BufRead for BufReader<R> {
 375     fn fill_buf(&mut self) -> io::Result<&[u8]> {
 376         self.buf.fill_buf(&mut self.inner)
 377     }
 378
 379     fn consume(&mut self, amt: usize) {
 380         self.buf.consume(amt)
 381     }
 382 }
 383
 384 #[stable(feature = "rust1", since = "1.0.0")]
 385 impl<R> fmt::Debug for BufReader<R>
 386 where
 387     R: fmt::Debug,
 388 {
 389     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 390         fmt.debug_struct("BufReader")
 391             .field("reader", &self.inner)
 392             .field(
 393                 "buffer",
 394                 &format_args!("{}/{}", self.buf.filled() - self.buf.pos(), self.capacity()),
 395             )
 396             .finish()
 397     }
 398 }
 399
 400 #[stable(feature = "rust1", since = "1.0.0")]
 401 impl<R: Seek> Seek for BufReader<R> {
 402     /// Seek to an offset, in bytes, in the underlying reader.
 403     ///
 404     /// The position used for seeking with <code>[SeekFrom::Current]\(_)</code> is the
 405     /// position the underlying reader would be at if the `BufReader<R>` had no
 406     /// internal buffer.
 407     ///
 408     /// Seeking always discards the internal buffer, even if the seek position
 409     /// would otherwise fall within it. This guarantees that calling
 410     /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader
 411     /// at the same position.
 412     ///
 413     /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`].
 414     ///
 415     /// See [`std::io::Seek`] for more details.
 416     ///
 417     /// Note: In the edge case where you're seeking with <code>[SeekFrom::Current]\(n)</code>
 418     /// where `n` minus the internal buffer length overflows an `i64`, two
 419     /// seeks will be performed instead of one. If the second seek returns
 420     /// [`Err`], the underlying reader will be left at the same position it would
 421     /// have if you called `seek` with <code>[SeekFrom::Current]\(0)</code>.
 422     ///
 423     /// [`std::io::Seek`]: Seek
 424     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 425         let result: u64;
 426         if let SeekFrom::Current(n) = pos {
 427             let remainder = (self.buf.filled() - self.buf.pos()) as i64;
 428             // it should be safe to assume that remainder fits within an i64 as the alternative
 429             // means we managed to allocate 8 exbibytes and that's absurd.
 430             // But it's not out of the realm of possibility for some weird underlying reader to
 431             // support seeking by i64::MIN so we need to handle underflow when subtracting
 432             // remainder.
 433             if let Some(offset) = n.checked_sub(remainder) {
 434                 result = self.inner.seek(SeekFrom::Current(offset))?;
 435             } else {
 436                 // seek backwards by our remainder, and then by the offset
 437                 self.inner.seek(SeekFrom::Current(-remainder))?;
 438                 self.discard_buffer();
 439                 result = self.inner.seek(SeekFrom::Current(n))?;
 440             }
 441         } else {
 442             // Seeking with Start/End doesn't care about our buffer length.
 443             result = self.inner.seek(pos)?;
 444         }
 445         self.discard_buffer();
 446         Ok(result)
 447     }
 448
 449     /// Returns the current seek position from the start of the stream.
 450     ///
 451     /// The value returned is equivalent to `self.seek(SeekFrom::Current(0))`
 452     /// but does not flush the internal buffer. Due to this optimization the
 453     /// function does not guarantee that calling `.into_inner()` immediately
 454     /// afterwards will yield the underlying reader at the same position. Use
 455     /// [`BufReader::seek`] instead if you require that guarantee.
 456     ///
 457     /// # Panics
 458     ///
 459     /// This function will panic if the position of the inner reader is smaller
 460     /// than the amount of buffered data. That can happen if the inner reader
 461     /// has an incorrect implementation of [`Seek::stream_position`], or if the
 462     /// position has gone out of sync due to calling [`Seek::seek`] directly on
 463     /// the underlying reader.
 464     ///
 465     /// # Example
 466     ///
 467     /// ```no_run
 468     /// use std::{
 469     ///     io::{self, BufRead, BufReader, Seek},
 470     ///     fs::File,
 471     /// };
 472     ///
 473     /// fn main() -> io::Result<()> {
 474     ///     let mut f = BufReader::new(File::open("foo.txt")?);
 475     ///
 476     ///     let before = f.stream_position()?;
 477     ///     f.read_line(&mut String::new())?;
 478     ///     let after = f.stream_position()?;
 479     ///
 480     ///     println!("The first line was {} bytes long", after - before);
 481     ///     Ok(())
 482     /// }
 483     /// ```
 484     fn stream_position(&mut self) -> io::Result<u64> {
 485         let remainder = (self.buf.filled() - self.buf.pos()) as u64;
 486         self.inner.stream_position().map(|pos| {
 487             pos.checked_sub(remainder).expect(
 488                 "overflow when subtracting remaining buffer size from inner stream position",
 489             )
 490         })
 491     }
 492 }
 493
 494 impl<T> SizeHint for BufReader<T> {
 495     #[inline]
 496     fn lower_bound(&self) -> usize {
 497         SizeHint::lower_bound(self.get_ref()) + self.buffer().len()
 498     }
 499
 500     #[inline]
 501     fn upper_bound(&self) -> Option<usize> {
 502         SizeHint::upper_bound(self.get_ref()).and_then(|up| self.buffer().len().checked_add(up))
 503     }
 504 }