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