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

   1 mod buffer;
   2
   3 use crate::fmt;
   4 use crate::io::{
   5     self, BufRead, IoSliceMut, Read, ReadBuf, 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 impl<R: Seek> BufReader<R> {
 228     /// Seeks relative to the current position. If the new position lies within the buffer,
 229     /// the buffer will not be flushed, allowing for more efficient seeks.
 230     /// This method does not return the location of the underlying reader, so the caller
 231     /// must track this information themselves if it is required.
 232     #[stable(feature = "bufreader_seek_relative", since = "1.53.0")]
 233     pub fn seek_relative(&mut self, offset: i64) -> io::Result<()> {
 234         let pos = self.buf.pos() as u64;
 235         if offset < 0 {
 236             if let Some(_) = pos.checked_sub((-offset) as u64) {
 237                 self.buf.unconsume((-offset) as usize);
 238                 return Ok(());
 239             }
 240         } else if let Some(new_pos) = pos.checked_add(offset as u64) {
 241             if new_pos <= self.buf.filled() as u64 {
 242                 self.buf.consume(offset as usize);
 243                 return Ok(());
 244             }
 245         }
 246
 247         self.seek(SeekFrom::Current(offset)).map(drop)
 248     }
 249 }
 250
 251 #[stable(feature = "rust1", since = "1.0.0")]
 252 impl<R: Read> Read for BufReader<R> {
 253     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 254         // If we don't have any buffered data and we're doing a massive read
 255         // (larger than our internal buffer), bypass our internal buffer
 256         // entirely.
 257         if self.buf.pos() == self.buf.filled() && buf.len() >= self.capacity() {
 258             self.discard_buffer();
 259             return self.inner.read(buf);
 260         }
 261         let nread = {
 262             let mut rem = self.fill_buf()?;
 263             rem.read(buf)?
 264         };
 265         self.consume(nread);
 266         Ok(nread)
 267     }
 268
 269     fn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> io::Result<()> {
 270         // If we don't have any buffered data and we're doing a massive read
 271         // (larger than our internal buffer), bypass our internal buffer
 272         // entirely.
 273         if self.buf.pos() == self.buf.filled() && buf.remaining() >= self.capacity() {
 274             self.discard_buffer();
 275             return self.inner.read_buf(buf);
 276         }
 277
 278         let prev = buf.filled_len();
 279
 280         let mut rem = self.fill_buf()?;
 281         rem.read_buf(buf)?;
 282
 283         self.consume(buf.filled_len() - prev); //slice impl of read_buf known to never unfill buf
 284
 285         Ok(())
 286     }
 287
 288     // Small read_exacts from a BufReader are extremely common when used with a deserializer.
 289     // The default implementation calls read in a loop, which results in surprisingly poor code
 290     // generation for the common path where the buffer has enough bytes to fill the passed-in
 291     // buffer.
 292     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
 293         if let Some(claimed) = self.buffer().get(..buf.len()) {
 294             buf.copy_from_slice(claimed);
 295             self.consume(claimed.len());
 296             return Ok(());
 297         }
 298
 299         crate::io::default_read_exact(self, buf)
 300     }
 301
 302     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 303         let total_len = bufs.iter().map(|b| b.len()).sum::<usize>();
 304         if self.buf.pos() == self.buf.filled() && total_len >= self.capacity() {
 305             self.discard_buffer();
 306             return self.inner.read_vectored(bufs);
 307         }
 308         let nread = {
 309             let mut rem = self.fill_buf()?;
 310             rem.read_vectored(bufs)?
 311         };
 312         self.consume(nread);
 313         Ok(nread)
 314     }
 315
 316     fn is_read_vectored(&self) -> bool {
 317         self.inner.is_read_vectored()
 318     }
 319
 320     // The inner reader might have an optimized `read_to_end`. Drain our buffer and then
 321     // delegate to the inner implementation.
 322     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
 323         let inner_buf = self.buffer();
 324         buf.extend_from_slice(inner_buf);
 325         let nread = inner_buf.len();
 326         self.discard_buffer();
 327         Ok(nread + self.inner.read_to_end(buf)?)
 328     }
 329
 330     // The inner reader might have an optimized `read_to_end`. Drain our buffer and then
 331     // delegate to the inner implementation.
 332     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
 333         // In the general `else` case below we must read bytes into a side buffer, check
 334         // that they are valid UTF-8, and then append them to `buf`. This requires a
 335         // potentially large memcpy.
 336         //
 337         // If `buf` is empty--the most common case--we can leverage `append_to_string`
 338         // to read directly into `buf`'s internal byte buffer, saving an allocation and
 339         // a memcpy.
 340         if buf.is_empty() {
 341             // `append_to_string`'s safety relies on the buffer only being appended to since
 342             // it only checks the UTF-8 validity of new data. If there were existing content in
 343             // `buf` then an untrustworthy reader (i.e. `self.inner`) could not only append
 344             // bytes but also modify existing bytes and render them invalid. On the other hand,
 345             // if `buf` is empty then by definition any writes must be appends and
 346             // `append_to_string` will validate all of the new bytes.
 347             unsafe { crate::io::append_to_string(buf, |b| self.read_to_end(b)) }
 348         } else {
 349             // We cannot append our byte buffer directly onto the `buf` String as there could
 350             // be an incomplete UTF-8 sequence that has only been partially read. We must read
 351             // everything into a side buffer first and then call `from_utf8` on the complete
 352             // buffer.
 353             let mut bytes = Vec::new();
 354             self.read_to_end(&mut bytes)?;
 355             let string = crate::str::from_utf8(&bytes).map_err(|_| {
 356                 io::const_io_error!(
 357                     io::ErrorKind::InvalidData,
 358                     "stream did not contain valid UTF-8",
 359                 )
 360             })?;
 361             *buf += string;
 362             Ok(string.len())
 363         }
 364     }
 365 }
 366
 367 #[stable(feature = "rust1", since = "1.0.0")]
 368 impl<R: Read> BufRead for BufReader<R> {
 369     fn fill_buf(&mut self) -> io::Result<&[u8]> {
 370         self.buf.fill_buf(&mut self.inner)
 371     }
 372
 373     fn consume(&mut self, amt: usize) {
 374         self.buf.consume(amt)
 375     }
 376 }
 377
 378 #[stable(feature = "rust1", since = "1.0.0")]
 379 impl<R> fmt::Debug for BufReader<R>
 380 where
 381     R: fmt::Debug,
 382 {
 383     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 384         fmt.debug_struct("BufReader")
 385             .field("reader", &self.inner)
 386             .field(
 387                 "buffer",
 388                 &format_args!("{}/{}", self.buf.filled() - self.buf.pos(), self.capacity()),
 389             )
 390             .finish()
 391     }
 392 }
 393
 394 #[stable(feature = "rust1", since = "1.0.0")]
 395 impl<R: Seek> Seek for BufReader<R> {
 396     /// Seek to an offset, in bytes, in the underlying reader.
 397     ///
 398     /// The position used for seeking with <code>[SeekFrom::Current]\(_)</code> is the
 399     /// position the underlying reader would be at if the `BufReader<R>` had no
 400     /// internal buffer.
 401     ///
 402     /// Seeking always discards the internal buffer, even if the seek position
 403     /// would otherwise fall within it. This guarantees that calling
 404     /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader
 405     /// at the same position.
 406     ///
 407     /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`].
 408     ///
 409     /// See [`std::io::Seek`] for more details.
 410     ///
 411     /// Note: In the edge case where you're seeking with <code>[SeekFrom::Current]\(n)</code>
 412     /// where `n` minus the internal buffer length overflows an `i64`, two
 413     /// seeks will be performed instead of one. If the second seek returns
 414     /// [`Err`], the underlying reader will be left at the same position it would
 415     /// have if you called `seek` with <code>[SeekFrom::Current]\(0)</code>.
 416     ///
 417     /// [`std::io::Seek`]: Seek
 418     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 419         let result: u64;
 420         if let SeekFrom::Current(n) = pos {
 421             let remainder = (self.buf.filled() - self.buf.pos()) as i64;
 422             // it should be safe to assume that remainder fits within an i64 as the alternative
 423             // means we managed to allocate 8 exbibytes and that's absurd.
 424             // But it's not out of the realm of possibility for some weird underlying reader to
 425             // support seeking by i64::MIN so we need to handle underflow when subtracting
 426             // remainder.
 427             if let Some(offset) = n.checked_sub(remainder) {
 428                 result = self.inner.seek(SeekFrom::Current(offset))?;
 429             } else {
 430                 // seek backwards by our remainder, and then by the offset
 431                 self.inner.seek(SeekFrom::Current(-remainder))?;
 432                 self.discard_buffer();
 433                 result = self.inner.seek(SeekFrom::Current(n))?;
 434             }
 435         } else {
 436             // Seeking with Start/End doesn't care about our buffer length.
 437             result = self.inner.seek(pos)?;
 438         }
 439         self.discard_buffer();
 440         Ok(result)
 441     }
 442
 443     /// Returns the current seek position from the start of the stream.
 444     ///
 445     /// The value returned is equivalent to `self.seek(SeekFrom::Current(0))`
 446     /// but does not flush the internal buffer. Due to this optimization the
 447     /// function does not guarantee that calling `.into_inner()` immediately
 448     /// afterwards will yield the underlying reader at the same position. Use
 449     /// [`BufReader::seek`] instead if you require that guarantee.
 450     ///
 451     /// # Panics
 452     ///
 453     /// This function will panic if the position of the inner reader is smaller
 454     /// than the amount of buffered data. That can happen if the inner reader
 455     /// has an incorrect implementation of [`Seek::stream_position`], or if the
 456     /// position has gone out of sync due to calling [`Seek::seek`] directly on
 457     /// the underlying reader.
 458     ///
 459     /// # Example
 460     ///
 461     /// ```no_run
 462     /// use std::{
 463     ///     io::{self, BufRead, BufReader, Seek},
 464     ///     fs::File,
 465     /// };
 466     ///
 467     /// fn main() -> io::Result<()> {
 468     ///     let mut f = BufReader::new(File::open("foo.txt")?);
 469     ///
 470     ///     let before = f.stream_position()?;
 471     ///     f.read_line(&mut String::new())?;
 472     ///     let after = f.stream_position()?;
 473     ///
 474     ///     println!("The first line was {} bytes long", after - before);
 475     ///     Ok(())
 476     /// }
 477     /// ```
 478     fn stream_position(&mut self) -> io::Result<u64> {
 479         let remainder = (self.buf.filled() - self.buf.pos()) as u64;
 480         self.inner.stream_position().map(|pos| {
 481             pos.checked_sub(remainder).expect(
 482                 "overflow when subtracting remaining buffer size from inner stream position",
 483             )
 484         })
 485     }
 486 }
 487
 488 impl<T> SizeHint for BufReader<T> {
 489     #[inline]
 490     fn lower_bound(&self) -> usize {
 491         SizeHint::lower_bound(self.get_ref()) + self.buffer().len()
 492     }
 493
 494     #[inline]
 495     fn upper_bound(&self) -> Option<usize> {
 496         SizeHint::upper_bound(self.get_ref()).and_then(|up| self.buffer().len().checked_add(up))
 497     }
 498 }