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