library/std/src/io/buffered.rs

   1 //! Buffering wrappers for I/O traits
   2
   3 use crate::io::prelude::*;
   4
   5 use crate::cmp;
   6 use crate::error;
   7 use crate::fmt;
   8 use crate::io::{
   9     self, Error, ErrorKind, Initializer, IoSlice, IoSliceMut, SeekFrom, DEFAULT_BUF_SIZE,
  10 };
  11 use crate::memchr;
  12
  13 /// The `BufReader<R>` struct adds buffering to any reader.
  14 ///
  15 /// It can be excessively inefficient to work directly with a [`Read`] instance.
  16 /// For example, every call to [`read`][`TcpStream::read`] on [`TcpStream`]
  17 /// results in a system call. A `BufReader<R>` performs large, infrequent reads on
  18 /// the underlying [`Read`] and maintains an in-memory buffer of the results.
  19 ///
  20 /// `BufReader<R>` can improve the speed of programs that make *small* and
  21 /// *repeated* read calls to the same file or network socket. It does not
  22 /// help when reading very large amounts at once, or reading just one or a few
  23 /// times. It also provides no advantage when reading from a source that is
  24 /// already in memory, like a [`Vec`]`<u8>`.
  25 ///
  26 /// When the `BufReader<R>` is dropped, the contents of its buffer will be
  27 /// discarded. Creating multiple instances of a `BufReader<R>` on the same
  28 /// stream can cause data loss. Reading from the underlying reader after
  29 /// unwrapping the `BufReader<R>` with [`BufReader::into_inner`] can also cause
  30 /// data loss.
  31 ///
  32 /// [`TcpStream::read`]: Read::read
  33 /// [`TcpStream`]: crate::net::TcpStream
  34 ///
  35 /// # Examples
  36 ///
  37 /// ```no_run
  38 /// use std::io::prelude::*;
  39 /// use std::io::BufReader;
  40 /// use std::fs::File;
  41 ///
  42 /// fn main() -> std::io::Result<()> {
  43 ///     let f = File::open("log.txt")?;
  44 ///     let mut reader = BufReader::new(f);
  45 ///
  46 ///     let mut line = String::new();
  47 ///     let len = reader.read_line(&mut line)?;
  48 ///     println!("First line is {} bytes long", len);
  49 ///     Ok(())
  50 /// }
  51 /// ```
  52 #[stable(feature = "rust1", since = "1.0.0")]
  53 pub struct BufReader<R> {
  54     inner: R,
  55     buf: Box<[u8]>,
  56     pos: usize,
  57     cap: usize,
  58 }
  59
  60 impl<R: Read> BufReader<R> {
  61     /// Creates a new `BufReader<R>` with a default buffer capacity. The default is currently 8 KB,
  62     /// but may change in the future.
  63     ///
  64     /// # Examples
  65     ///
  66     /// ```no_run
  67     /// use std::io::BufReader;
  68     /// use std::fs::File;
  69     ///
  70     /// fn main() -> std::io::Result<()> {
  71     ///     let f = File::open("log.txt")?;
  72     ///     let reader = BufReader::new(f);
  73     ///     Ok(())
  74     /// }
  75     /// ```
  76     #[stable(feature = "rust1", since = "1.0.0")]
  77     pub fn new(inner: R) -> BufReader<R> {
  78         BufReader::with_capacity(DEFAULT_BUF_SIZE, inner)
  79     }
  80
  81     /// Creates a new `BufReader<R>` with the specified buffer capacity.
  82     ///
  83     /// # Examples
  84     ///
  85     /// Creating a buffer with ten bytes of capacity:
  86     ///
  87     /// ```no_run
  88     /// use std::io::BufReader;
  89     /// use std::fs::File;
  90     ///
  91     /// fn main() -> std::io::Result<()> {
  92     ///     let f = File::open("log.txt")?;
  93     ///     let reader = BufReader::with_capacity(10, f);
  94     ///     Ok(())
  95     /// }
  96     /// ```
  97     #[stable(feature = "rust1", since = "1.0.0")]
  98     pub fn with_capacity(capacity: usize, inner: R) -> BufReader<R> {
  99         unsafe {
 100             let mut buffer = Vec::with_capacity(capacity);
 101             buffer.set_len(capacity);
 102             inner.initializer().initialize(&mut buffer);
 103             BufReader { inner, buf: buffer.into_boxed_slice(), pos: 0, cap: 0 }
 104         }
 105     }
 106 }
 107
 108 impl<R> BufReader<R> {
 109     /// Gets a reference to the underlying reader.
 110     ///
 111     /// It is inadvisable to directly read from the underlying reader.
 112     ///
 113     /// # Examples
 114     ///
 115     /// ```no_run
 116     /// use std::io::BufReader;
 117     /// use std::fs::File;
 118     ///
 119     /// fn main() -> std::io::Result<()> {
 120     ///     let f1 = File::open("log.txt")?;
 121     ///     let reader = BufReader::new(f1);
 122     ///
 123     ///     let f2 = reader.get_ref();
 124     ///     Ok(())
 125     /// }
 126     /// ```
 127     #[stable(feature = "rust1", since = "1.0.0")]
 128     pub fn get_ref(&self) -> &R {
 129         &self.inner
 130     }
 131
 132     /// Gets a mutable reference to the underlying reader.
 133     ///
 134     /// It is inadvisable to directly read from the underlying reader.
 135     ///
 136     /// # Examples
 137     ///
 138     /// ```no_run
 139     /// use std::io::BufReader;
 140     /// use std::fs::File;
 141     ///
 142     /// fn main() -> std::io::Result<()> {
 143     ///     let f1 = File::open("log.txt")?;
 144     ///     let mut reader = BufReader::new(f1);
 145     ///
 146     ///     let f2 = reader.get_mut();
 147     ///     Ok(())
 148     /// }
 149     /// ```
 150     #[stable(feature = "rust1", since = "1.0.0")]
 151     pub fn get_mut(&mut self) -> &mut R {
 152         &mut self.inner
 153     }
 154
 155     /// Returns a reference to the internally buffered data.
 156     ///
 157     /// Unlike [`fill_buf`], this will not attempt to fill the buffer if it is empty.
 158     ///
 159     /// [`fill_buf`]: BufRead::fill_buf
 160     ///
 161     /// # Examples
 162     ///
 163     /// ```no_run
 164     /// use std::io::{BufReader, BufRead};
 165     /// use std::fs::File;
 166     ///
 167     /// fn main() -> std::io::Result<()> {
 168     ///     let f = File::open("log.txt")?;
 169     ///     let mut reader = BufReader::new(f);
 170     ///     assert!(reader.buffer().is_empty());
 171     ///
 172     ///     if reader.fill_buf()?.len() > 0 {
 173     ///         assert!(!reader.buffer().is_empty());
 174     ///     }
 175     ///     Ok(())
 176     /// }
 177     /// ```
 178     #[stable(feature = "bufreader_buffer", since = "1.37.0")]
 179     pub fn buffer(&self) -> &[u8] {
 180         &self.buf[self.pos..self.cap]
 181     }
 182
 183     /// Returns the number of bytes the internal buffer can hold at once.
 184     ///
 185     /// # Examples
 186     ///
 187     /// ```no_run
 188     /// use std::io::{BufReader, BufRead};
 189     /// use std::fs::File;
 190     ///
 191     /// fn main() -> std::io::Result<()> {
 192     ///     let f = File::open("log.txt")?;
 193     ///     let mut reader = BufReader::new(f);
 194     ///
 195     ///     let capacity = reader.capacity();
 196     ///     let buffer = reader.fill_buf()?;
 197     ///     assert!(buffer.len() <= capacity);
 198     ///     Ok(())
 199     /// }
 200     /// ```
 201     #[stable(feature = "buffered_io_capacity", since = "1.46.0")]
 202     pub fn capacity(&self) -> usize {
 203         self.buf.len()
 204     }
 205
 206     /// Unwraps this `BufReader<R>`, returning the underlying reader.
 207     ///
 208     /// Note that any leftover data in the internal buffer is lost. Therefore,
 209     /// a following read from the underlying reader may lead to data loss.
 210     ///
 211     /// # Examples
 212     ///
 213     /// ```no_run
 214     /// use std::io::BufReader;
 215     /// use std::fs::File;
 216     ///
 217     /// fn main() -> std::io::Result<()> {
 218     ///     let f1 = File::open("log.txt")?;
 219     ///     let reader = BufReader::new(f1);
 220     ///
 221     ///     let f2 = reader.into_inner();
 222     ///     Ok(())
 223     /// }
 224     /// ```
 225     #[stable(feature = "rust1", since = "1.0.0")]
 226     pub fn into_inner(self) -> R {
 227         self.inner
 228     }
 229
 230     /// Invalidates all data in the internal buffer.
 231     #[inline]
 232     fn discard_buffer(&mut self) {
 233         self.pos = 0;
 234         self.cap = 0;
 235     }
 236 }
 237
 238 impl<R: 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     #[unstable(feature = "bufreader_seek_relative", issue = "31100")]
 244     pub fn seek_relative(&mut self, offset: i64) -> io::Result<()> {
 245         let pos = self.pos as u64;
 246         if offset < 0 {
 247             if let Some(new_pos) = pos.checked_sub((-offset) as u64) {
 248                 self.pos = new_pos as usize;
 249                 return Ok(());
 250             }
 251         } else {
 252             if let Some(new_pos) = pos.checked_add(offset as u64) {
 253                 if new_pos <= self.cap as u64 {
 254                     self.pos = new_pos as usize;
 255                     return Ok(());
 256                 }
 257             }
 258         }
 259         self.seek(SeekFrom::Current(offset)).map(drop)
 260     }
 261 }
 262
 263 #[stable(feature = "rust1", since = "1.0.0")]
 264 impl<R: Read> Read for BufReader<R> {
 265     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 266         // If we don't have any buffered data and we're doing a massive read
 267         // (larger than our internal buffer), bypass our internal buffer
 268         // entirely.
 269         if self.pos == self.cap && buf.len() >= self.buf.len() {
 270             self.discard_buffer();
 271             return self.inner.read(buf);
 272         }
 273         let nread = {
 274             let mut rem = self.fill_buf()?;
 275             rem.read(buf)?
 276         };
 277         self.consume(nread);
 278         Ok(nread)
 279     }
 280
 281     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 282         let total_len = bufs.iter().map(|b| b.len()).sum::<usize>();
 283         if self.pos == self.cap && total_len >= self.buf.len() {
 284             self.discard_buffer();
 285             return self.inner.read_vectored(bufs);
 286         }
 287         let nread = {
 288             let mut rem = self.fill_buf()?;
 289             rem.read_vectored(bufs)?
 290         };
 291         self.consume(nread);
 292         Ok(nread)
 293     }
 294
 295     fn is_read_vectored(&self) -> bool {
 296         self.inner.is_read_vectored()
 297     }
 298
 299     // we can't skip unconditionally because of the large buffer case in read.
 300     unsafe fn initializer(&self) -> Initializer {
 301         self.inner.initializer()
 302     }
 303 }
 304
 305 #[stable(feature = "rust1", since = "1.0.0")]
 306 impl<R: Read> BufRead for BufReader<R> {
 307     fn fill_buf(&mut self) -> io::Result<&[u8]> {
 308         // If we've reached the end of our internal buffer then we need to fetch
 309         // some more data from the underlying reader.
 310         // Branch using `>=` instead of the more correct `==`
 311         // to tell the compiler that the pos..cap slice is always valid.
 312         if self.pos >= self.cap {
 313             debug_assert!(self.pos == self.cap);
 314             self.cap = self.inner.read(&mut self.buf)?;
 315             self.pos = 0;
 316         }
 317         Ok(&self.buf[self.pos..self.cap])
 318     }
 319
 320     fn consume(&mut self, amt: usize) {
 321         self.pos = cmp::min(self.pos + amt, self.cap);
 322     }
 323 }
 324
 325 #[stable(feature = "rust1", since = "1.0.0")]
 326 impl<R> fmt::Debug for BufReader<R>
 327 where
 328     R: fmt::Debug,
 329 {
 330     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 331         fmt.debug_struct("BufReader")
 332             .field("reader", &self.inner)
 333             .field("buffer", &format_args!("{}/{}", self.cap - self.pos, self.buf.len()))
 334             .finish()
 335     }
 336 }
 337
 338 #[stable(feature = "rust1", since = "1.0.0")]
 339 impl<R: Seek> Seek for BufReader<R> {
 340     /// Seek to an offset, in bytes, in the underlying reader.
 341     ///
 342     /// The position used for seeking with [`SeekFrom::Current`]`(_)` is the
 343     /// position the underlying reader would be at if the `BufReader<R>` had no
 344     /// internal buffer.
 345     ///
 346     /// Seeking always discards the internal buffer, even if the seek position
 347     /// would otherwise fall within it. This guarantees that calling
 348     /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader
 349     /// at the same position.
 350     ///
 351     /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`].
 352     ///
 353     /// See [`std::io::Seek`] for more details.
 354     ///
 355     /// Note: In the edge case where you're seeking with [`SeekFrom::Current`]`(n)`
 356     /// where `n` minus the internal buffer length overflows an `i64`, two
 357     /// seeks will be performed instead of one. If the second seek returns
 358     /// [`Err`], the underlying reader will be left at the same position it would
 359     /// have if you called `seek` with [`SeekFrom::Current`]`(0)`.
 360     ///
 361     /// [`std::io::Seek`]: Seek
 362     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 363         let result: u64;
 364         if let SeekFrom::Current(n) = pos {
 365             let remainder = (self.cap - self.pos) as i64;
 366             // it should be safe to assume that remainder fits within an i64 as the alternative
 367             // means we managed to allocate 8 exbibytes and that's absurd.
 368             // But it's not out of the realm of possibility for some weird underlying reader to
 369             // support seeking by i64::MIN so we need to handle underflow when subtracting
 370             // remainder.
 371             if let Some(offset) = n.checked_sub(remainder) {
 372                 result = self.inner.seek(SeekFrom::Current(offset))?;
 373             } else {
 374                 // seek backwards by our remainder, and then by the offset
 375                 self.inner.seek(SeekFrom::Current(-remainder))?;
 376                 self.discard_buffer();
 377                 result = self.inner.seek(SeekFrom::Current(n))?;
 378             }
 379         } else {
 380             // Seeking with Start/End doesn't care about our buffer length.
 381             result = self.inner.seek(pos)?;
 382         }
 383         self.discard_buffer();
 384         Ok(result)
 385     }
 386 }
 387
 388 /// Wraps a writer and buffers its output.
 389 ///
 390 /// It can be excessively inefficient to work directly with something that
 391 /// implements [`Write`]. For example, every call to
 392 /// [`write`][`TcpStream::write`] on [`TcpStream`] results in a system call. A
 393 /// `BufWriter<W>` keeps an in-memory buffer of data and writes it to an underlying
 394 /// writer in large, infrequent batches.
 395 ///
 396 /// `BufWriter<W>` can improve the speed of programs that make *small* and
 397 /// *repeated* write calls to the same file or network socket. It does not
 398 /// help when writing very large amounts at once, or writing just one or a few
 399 /// times. It also provides no advantage when writing to a destination that is
 400 /// in memory, like a [`Vec`]<u8>`.
 401 ///
 402 /// It is critical to call [`flush`] before `BufWriter<W>` is dropped. Though
 403 /// dropping will attempt to flush the contents of the buffer, any errors
 404 /// that happen in the process of dropping will be ignored. Calling [`flush`]
 405 /// ensures that the buffer is empty and thus dropping will not even attempt
 406 /// file operations.
 407 ///
 408 /// # Examples
 409 ///
 410 /// Let's write the numbers one through ten to a [`TcpStream`]:
 411 ///
 412 /// ```no_run
 413 /// use std::io::prelude::*;
 414 /// use std::net::TcpStream;
 415 ///
 416 /// let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();
 417 ///
 418 /// for i in 0..10 {
 419 ///     stream.write(&[i+1]).unwrap();
 420 /// }
 421 /// ```
 422 ///
 423 /// Because we're not buffering, we write each one in turn, incurring the
 424 /// overhead of a system call per byte written. We can fix this with a
 425 /// `BufWriter<W>`:
 426 ///
 427 /// ```no_run
 428 /// use std::io::prelude::*;
 429 /// use std::io::BufWriter;
 430 /// use std::net::TcpStream;
 431 ///
 432 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 433 ///
 434 /// for i in 0..10 {
 435 ///     stream.write(&[i+1]).unwrap();
 436 /// }
 437 /// stream.flush().unwrap();
 438 /// ```
 439 ///
 440 /// By wrapping the stream with a `BufWriter<W>`, these ten writes are all grouped
 441 /// together by the buffer and will all be written out in one system call when
 442 /// the `stream` is flushed.
 443 ///
 444 /// [`TcpStream::write`]: Write::write
 445 /// [`TcpStream`]: crate::net::TcpStream
 446 /// [`flush`]: Write::flush
 447 #[stable(feature = "rust1", since = "1.0.0")]
 448 pub struct BufWriter<W: Write> {
 449     inner: Option<W>,
 450     buf: Vec<u8>,
 451     // #30888: If the inner writer panics in a call to write, we don't want to
 452     // write the buffered data a second time in BufWriter's destructor. This
 453     // flag tells the Drop impl if it should skip the flush.
 454     panicked: bool,
 455 }
 456
 457 /// An error returned by [`BufWriter::into_inner`] which combines an error that
 458 /// happened while writing out the buffer, and the buffered writer object
 459 /// which may be used to recover from the condition.
 460 ///
 461 /// # Examples
 462 ///
 463 /// ```no_run
 464 /// use std::io::BufWriter;
 465 /// use std::net::TcpStream;
 466 ///
 467 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 468 ///
 469 /// // do stuff with the stream
 470 ///
 471 /// // we want to get our `TcpStream` back, so let's try:
 472 ///
 473 /// let stream = match stream.into_inner() {
 474 ///     Ok(s) => s,
 475 ///     Err(e) => {
 476 ///         // Here, e is an IntoInnerError
 477 ///         panic!("An error occurred");
 478 ///     }
 479 /// };
 480 /// ```
 481 #[derive(Debug)]
 482 #[stable(feature = "rust1", since = "1.0.0")]
 483 pub struct IntoInnerError<W>(W, Error);
 484
 485 impl<W: Write> BufWriter<W> {
 486     /// Creates a new `BufWriter<W>` with a default buffer capacity. The default is currently 8 KB,
 487     /// but may change in the future.
 488     ///
 489     /// # Examples
 490     ///
 491     /// ```no_run
 492     /// use std::io::BufWriter;
 493     /// use std::net::TcpStream;
 494     ///
 495     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 496     /// ```
 497     #[stable(feature = "rust1", since = "1.0.0")]
 498     pub fn new(inner: W) -> BufWriter<W> {
 499         BufWriter::with_capacity(DEFAULT_BUF_SIZE, inner)
 500     }
 501
 502     /// Creates a new `BufWriter<W>` with the specified buffer capacity.
 503     ///
 504     /// # Examples
 505     ///
 506     /// Creating a buffer with a buffer of a hundred bytes.
 507     ///
 508     /// ```no_run
 509     /// use std::io::BufWriter;
 510     /// use std::net::TcpStream;
 511     ///
 512     /// let stream = TcpStream::connect("127.0.0.1:34254").unwrap();
 513     /// let mut buffer = BufWriter::with_capacity(100, stream);
 514     /// ```
 515     #[stable(feature = "rust1", since = "1.0.0")]
 516     pub fn with_capacity(capacity: usize, inner: W) -> BufWriter<W> {
 517         BufWriter { inner: Some(inner), buf: Vec::with_capacity(capacity), panicked: false }
 518     }
 519
 520     fn flush_buf(&mut self) -> io::Result<()> {
 521         let mut written = 0;
 522         let len = self.buf.len();
 523         let mut ret = Ok(());
 524         while written < len {
 525             self.panicked = true;
 526             let r = self.inner.as_mut().unwrap().write(&self.buf[written..]);
 527             self.panicked = false;
 528
 529             match r {
 530                 Ok(0) => {
 531                     ret =
 532                         Err(Error::new(ErrorKind::WriteZero, "failed to write the buffered data"));
 533                     break;
 534                 }
 535                 Ok(n) => written += n,
 536                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {}
 537                 Err(e) => {
 538                     ret = Err(e);
 539                     break;
 540                 }
 541             }
 542         }
 543         if written > 0 {
 544             self.buf.drain(..written);
 545         }
 546         ret
 547     }
 548
 549     /// Gets a reference to the underlying writer.
 550     ///
 551     /// # Examples
 552     ///
 553     /// ```no_run
 554     /// use std::io::BufWriter;
 555     /// use std::net::TcpStream;
 556     ///
 557     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 558     ///
 559     /// // we can use reference just like buffer
 560     /// let reference = buffer.get_ref();
 561     /// ```
 562     #[stable(feature = "rust1", since = "1.0.0")]
 563     pub fn get_ref(&self) -> &W {
 564         self.inner.as_ref().unwrap()
 565     }
 566
 567     /// Gets a mutable reference to the underlying writer.
 568     ///
 569     /// It is inadvisable to directly write to the underlying writer.
 570     ///
 571     /// # Examples
 572     ///
 573     /// ```no_run
 574     /// use std::io::BufWriter;
 575     /// use std::net::TcpStream;
 576     ///
 577     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 578     ///
 579     /// // we can use reference just like buffer
 580     /// let reference = buffer.get_mut();
 581     /// ```
 582     #[stable(feature = "rust1", since = "1.0.0")]
 583     pub fn get_mut(&mut self) -> &mut W {
 584         self.inner.as_mut().unwrap()
 585     }
 586
 587     /// Returns a reference to the internally buffered data.
 588     ///
 589     /// # Examples
 590     ///
 591     /// ```no_run
 592     /// use std::io::BufWriter;
 593     /// use std::net::TcpStream;
 594     ///
 595     /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 596     ///
 597     /// // See how many bytes are currently buffered
 598     /// let bytes_buffered = buf_writer.buffer().len();
 599     /// ```
 600     #[stable(feature = "bufreader_buffer", since = "1.37.0")]
 601     pub fn buffer(&self) -> &[u8] {
 602         &self.buf
 603     }
 604
 605     /// Returns the number of bytes the internal buffer can hold without flushing.
 606     ///
 607     /// # Examples
 608     ///
 609     /// ```no_run
 610     /// use std::io::BufWriter;
 611     /// use std::net::TcpStream;
 612     ///
 613     /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 614     ///
 615     /// // Check the capacity of the inner buffer
 616     /// let capacity = buf_writer.capacity();
 617     /// // Calculate how many bytes can be written without flushing
 618     /// let without_flush = capacity - buf_writer.buffer().len();
 619     /// ```
 620     #[stable(feature = "buffered_io_capacity", since = "1.46.0")]
 621     pub fn capacity(&self) -> usize {
 622         self.buf.capacity()
 623     }
 624
 625     /// Unwraps this `BufWriter<W>`, returning the underlying writer.
 626     ///
 627     /// The buffer is written out before returning the writer.
 628     ///
 629     /// # Errors
 630     ///
 631     /// An [`Err`] will be returned if an error occurs while flushing the buffer.
 632     ///
 633     /// # Examples
 634     ///
 635     /// ```no_run
 636     /// use std::io::BufWriter;
 637     /// use std::net::TcpStream;
 638     ///
 639     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 640     ///
 641     /// // unwrap the TcpStream and flush the buffer
 642     /// let stream = buffer.into_inner().unwrap();
 643     /// ```
 644     #[stable(feature = "rust1", since = "1.0.0")]
 645     pub fn into_inner(mut self) -> Result<W, IntoInnerError<BufWriter<W>>> {
 646         match self.flush_buf() {
 647             Err(e) => Err(IntoInnerError(self, e)),
 648             Ok(()) => Ok(self.inner.take().unwrap()),
 649         }
 650     }
 651 }
 652
 653 #[stable(feature = "rust1", since = "1.0.0")]
 654 impl<W: Write> Write for BufWriter<W> {
 655     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 656         if self.buf.len() + buf.len() > self.buf.capacity() {
 657             self.flush_buf()?;
 658         }
 659         if buf.len() >= self.buf.capacity() {
 660             self.panicked = true;
 661             let r = self.get_mut().write(buf);
 662             self.panicked = false;
 663             r
 664         } else {
 665             self.buf.write(buf)
 666         }
 667     }
 668
 669     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 670         let total_len = bufs.iter().map(|b| b.len()).sum::<usize>();
 671         if self.buf.len() + total_len > self.buf.capacity() {
 672             self.flush_buf()?;
 673         }
 674         if total_len >= self.buf.capacity() {
 675             self.panicked = true;
 676             let r = self.get_mut().write_vectored(bufs);
 677             self.panicked = false;
 678             r
 679         } else {
 680             self.buf.write_vectored(bufs)
 681         }
 682     }
 683
 684     fn is_write_vectored(&self) -> bool {
 685         self.get_ref().is_write_vectored()
 686     }
 687
 688     fn flush(&mut self) -> io::Result<()> {
 689         self.flush_buf().and_then(|()| self.get_mut().flush())
 690     }
 691 }
 692
 693 #[stable(feature = "rust1", since = "1.0.0")]
 694 impl<W: Write> fmt::Debug for BufWriter<W>
 695 where
 696     W: fmt::Debug,
 697 {
 698     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 699         fmt.debug_struct("BufWriter")
 700             .field("writer", &self.inner.as_ref().unwrap())
 701             .field("buffer", &format_args!("{}/{}", self.buf.len(), self.buf.capacity()))
 702             .finish()
 703     }
 704 }
 705
 706 #[stable(feature = "rust1", since = "1.0.0")]
 707 impl<W: Write + Seek> Seek for BufWriter<W> {
 708     /// Seek to the offset, in bytes, in the underlying writer.
 709     ///
 710     /// Seeking always writes out the internal buffer before seeking.
 711     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 712         self.flush_buf().and_then(|_| self.get_mut().seek(pos))
 713     }
 714 }
 715
 716 #[stable(feature = "rust1", since = "1.0.0")]
 717 impl<W: Write> Drop for BufWriter<W> {
 718     fn drop(&mut self) {
 719         if self.inner.is_some() && !self.panicked {
 720             // dtors should not panic, so we ignore a failed flush
 721             let _r = self.flush_buf();
 722         }
 723     }
 724 }
 725
 726 impl<W> IntoInnerError<W> {
 727     /// Returns the error which caused the call to [`BufWriter::into_inner()`]
 728     /// to fail.
 729     ///
 730     /// This error was returned when attempting to write the internal buffer.
 731     ///
 732     /// # Examples
 733     ///
 734     /// ```no_run
 735     /// use std::io::BufWriter;
 736     /// use std::net::TcpStream;
 737     ///
 738     /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 739     ///
 740     /// // do stuff with the stream
 741     ///
 742     /// // we want to get our `TcpStream` back, so let's try:
 743     ///
 744     /// let stream = match stream.into_inner() {
 745     ///     Ok(s) => s,
 746     ///     Err(e) => {
 747     ///         // Here, e is an IntoInnerError, let's log the inner error.
 748     ///         //
 749     ///         // We'll just 'log' to stdout for this example.
 750     ///         println!("{}", e.error());
 751     ///
 752     ///         panic!("An unexpected error occurred.");
 753     ///     }
 754     /// };
 755     /// ```
 756     #[stable(feature = "rust1", since = "1.0.0")]
 757     pub fn error(&self) -> &Error {
 758         &self.1
 759     }
 760
 761     /// Returns the buffered writer instance which generated the error.
 762     ///
 763     /// The returned object can be used for error recovery, such as
 764     /// re-inspecting the buffer.
 765     ///
 766     /// # Examples
 767     ///
 768     /// ```no_run
 769     /// use std::io::BufWriter;
 770     /// use std::net::TcpStream;
 771     ///
 772     /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 773     ///
 774     /// // do stuff with the stream
 775     ///
 776     /// // we want to get our `TcpStream` back, so let's try:
 777     ///
 778     /// let stream = match stream.into_inner() {
 779     ///     Ok(s) => s,
 780     ///     Err(e) => {
 781     ///         // Here, e is an IntoInnerError, let's re-examine the buffer:
 782     ///         let buffer = e.into_inner();
 783     ///
 784     ///         // do stuff to try to recover
 785     ///
 786     ///         // afterwards, let's just return the stream
 787     ///         buffer.into_inner().unwrap()
 788     ///     }
 789     /// };
 790     /// ```
 791     #[stable(feature = "rust1", since = "1.0.0")]
 792     pub fn into_inner(self) -> W {
 793         self.0
 794     }
 795 }
 796
 797 #[stable(feature = "rust1", since = "1.0.0")]
 798 impl<W> From<IntoInnerError<W>> for Error {
 799     fn from(iie: IntoInnerError<W>) -> Error {
 800         iie.1
 801     }
 802 }
 803
 804 #[stable(feature = "rust1", since = "1.0.0")]
 805 impl<W: Send + fmt::Debug> error::Error for IntoInnerError<W> {
 806     #[allow(deprecated, deprecated_in_future)]
 807     fn description(&self) -> &str {
 808         error::Error::description(self.error())
 809     }
 810 }
 811
 812 #[stable(feature = "rust1", since = "1.0.0")]
 813 impl<W> fmt::Display for IntoInnerError<W> {
 814     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 815         self.error().fmt(f)
 816     }
 817 }
 818
 819 /// Wraps a writer and buffers output to it, flushing whenever a newline
 820 /// (`0x0a`, `'\n'`) is detected.
 821 ///
 822 /// The [`BufWriter`] struct wraps a writer and buffers its output.
 823 /// But it only does this batched write when it goes out of scope, or when the
 824 /// internal buffer is full. Sometimes, you'd prefer to write each line as it's
 825 /// completed, rather than the entire buffer at once. Enter `LineWriter`. It
 826 /// does exactly that.
 827 ///
 828 /// Like [`BufWriter`], a `LineWriter`’s buffer will also be flushed when the
 829 /// `LineWriter` goes out of scope or when its internal buffer is full.
 830 ///
 831 /// If there's still a partial line in the buffer when the `LineWriter` is
 832 /// dropped, it will flush those contents.
 833 ///
 834 /// # Examples
 835 ///
 836 /// We can use `LineWriter` to write one line at a time, significantly
 837 /// reducing the number of actual writes to the file.
 838 ///
 839 /// ```no_run
 840 /// use std::fs::{self, File};
 841 /// use std::io::prelude::*;
 842 /// use std::io::LineWriter;
 843 ///
 844 /// fn main() -> std::io::Result<()> {
 845 ///     let road_not_taken = b"I shall be telling this with a sigh
 846 /// Somewhere ages and ages hence:
 847 /// Two roads diverged in a wood, and I -
 848 /// I took the one less traveled by,
 849 /// And that has made all the difference.";
 850 ///
 851 ///     let file = File::create("poem.txt")?;
 852 ///     let mut file = LineWriter::new(file);
 853 ///
 854 ///     file.write_all(b"I shall be telling this with a sigh")?;
 855 ///
 856 ///     // No bytes are written until a newline is encountered (or
 857 ///     // the internal buffer is filled).
 858 ///     assert_eq!(fs::read_to_string("poem.txt")?, "");
 859 ///     file.write_all(b"\n")?;
 860 ///     assert_eq!(
 861 ///         fs::read_to_string("poem.txt")?,
 862 ///         "I shall be telling this with a sigh\n",
 863 ///     );
 864 ///
 865 ///     // Write the rest of the poem.
 866 ///     file.write_all(b"Somewhere ages and ages hence:
 867 /// Two roads diverged in a wood, and I -
 868 /// I took the one less traveled by,
 869 /// And that has made all the difference.")?;
 870 ///
 871 ///     // The last line of the poem doesn't end in a newline, so
 872 ///     // we have to flush or drop the `LineWriter` to finish
 873 ///     // writing.
 874 ///     file.flush()?;
 875 ///
 876 ///     // Confirm the whole poem was written.
 877 ///     assert_eq!(fs::read("poem.txt")?, &road_not_taken[..]);
 878 ///     Ok(())
 879 /// }
 880 /// ```
 881 #[stable(feature = "rust1", since = "1.0.0")]
 882 pub struct LineWriter<W: Write> {
 883     inner: BufWriter<W>,
 884     need_flush: bool,
 885 }
 886
 887 impl<W: Write> LineWriter<W> {
 888     /// Creates a new `LineWriter`.
 889     ///
 890     /// # Examples
 891     ///
 892     /// ```no_run
 893     /// use std::fs::File;
 894     /// use std::io::LineWriter;
 895     ///
 896     /// fn main() -> std::io::Result<()> {
 897     ///     let file = File::create("poem.txt")?;
 898     ///     let file = LineWriter::new(file);
 899     ///     Ok(())
 900     /// }
 901     /// ```
 902     #[stable(feature = "rust1", since = "1.0.0")]
 903     pub fn new(inner: W) -> LineWriter<W> {
 904         // Lines typically aren't that long, don't use a giant buffer
 905         LineWriter::with_capacity(1024, inner)
 906     }
 907
 908     /// Creates a new `LineWriter` with a specified capacity for the internal
 909     /// buffer.
 910     ///
 911     /// # Examples
 912     ///
 913     /// ```no_run
 914     /// use std::fs::File;
 915     /// use std::io::LineWriter;
 916     ///
 917     /// fn main() -> std::io::Result<()> {
 918     ///     let file = File::create("poem.txt")?;
 919     ///     let file = LineWriter::with_capacity(100, file);
 920     ///     Ok(())
 921     /// }
 922     /// ```
 923     #[stable(feature = "rust1", since = "1.0.0")]
 924     pub fn with_capacity(capacity: usize, inner: W) -> LineWriter<W> {
 925         LineWriter { inner: BufWriter::with_capacity(capacity, inner), need_flush: false }
 926     }
 927
 928     /// Gets a reference to the underlying writer.
 929     ///
 930     /// # Examples
 931     ///
 932     /// ```no_run
 933     /// use std::fs::File;
 934     /// use std::io::LineWriter;
 935     ///
 936     /// fn main() -> std::io::Result<()> {
 937     ///     let file = File::create("poem.txt")?;
 938     ///     let file = LineWriter::new(file);
 939     ///
 940     ///     let reference = file.get_ref();
 941     ///     Ok(())
 942     /// }
 943     /// ```
 944     #[stable(feature = "rust1", since = "1.0.0")]
 945     pub fn get_ref(&self) -> &W {
 946         self.inner.get_ref()
 947     }
 948
 949     /// Gets a mutable reference to the underlying writer.
 950     ///
 951     /// Caution must be taken when calling methods on the mutable reference
 952     /// returned as extra writes could corrupt the output stream.
 953     ///
 954     /// # Examples
 955     ///
 956     /// ```no_run
 957     /// use std::fs::File;
 958     /// use std::io::LineWriter;
 959     ///
 960     /// fn main() -> std::io::Result<()> {
 961     ///     let file = File::create("poem.txt")?;
 962     ///     let mut file = LineWriter::new(file);
 963     ///
 964     ///     // we can use reference just like file
 965     ///     let reference = file.get_mut();
 966     ///     Ok(())
 967     /// }
 968     /// ```
 969     #[stable(feature = "rust1", since = "1.0.0")]
 970     pub fn get_mut(&mut self) -> &mut W {
 971         self.inner.get_mut()
 972     }
 973
 974     /// Unwraps this `LineWriter`, returning the underlying writer.
 975     ///
 976     /// The internal buffer is written out before returning the writer.
 977     ///
 978     /// # Errors
 979     ///
 980     /// An [`Err`] will be returned if an error occurs while flushing the buffer.
 981     ///
 982     /// # Examples
 983     ///
 984     /// ```no_run
 985     /// use std::fs::File;
 986     /// use std::io::LineWriter;
 987     ///
 988     /// fn main() -> std::io::Result<()> {
 989     ///     let file = File::create("poem.txt")?;
 990     ///
 991     ///     let writer: LineWriter<File> = LineWriter::new(file);
 992     ///
 993     ///     let file: File = writer.into_inner()?;
 994     ///     Ok(())
 995     /// }
 996     /// ```
 997     #[stable(feature = "rust1", since = "1.0.0")]
 998     pub fn into_inner(self) -> Result<W, IntoInnerError<LineWriter<W>>> {
 999         self.inner.into_inner().map_err(|IntoInnerError(buf, e)| {
1000             IntoInnerError(LineWriter { inner: buf, need_flush: false }, e)
1001         })
1002     }
1003 }
1004
1005 #[stable(feature = "rust1", since = "1.0.0")]
1006 impl<W: Write> Write for LineWriter<W> {
1007     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1008         if self.need_flush {
1009             self.flush()?;
1010         }
1011
1012         // Find the last newline character in the buffer provided. If found then
1013         // we're going to write all the data up to that point and then flush,
1014         // otherwise we just write the whole block to the underlying writer.
1015         let i = match memchr::memrchr(b'\n', buf) {
1016             Some(i) => i,
1017             None => return self.inner.write(buf),
1018         };
1019
1020         // Ok, we're going to write a partial amount of the data given first
1021         // followed by flushing the newline. After we've successfully written
1022         // some data then we *must* report that we wrote that data, so future
1023         // errors are ignored. We set our internal `need_flush` flag, though, in
1024         // case flushing fails and we need to try it first next time.
1025         let n = self.inner.write(&buf[..=i])?;
1026         self.need_flush = true;
1027         if self.flush().is_err() || n != i + 1 {
1028             return Ok(n);
1029         }
1030
1031         // At this point we successfully wrote `i + 1` bytes and flushed it out,
1032         // meaning that the entire line is now flushed out on the screen. While
1033         // we can attempt to finish writing the rest of the data provided.
1034         // Remember though that we ignore errors here as we've successfully
1035         // written data, so we need to report that.
1036         match self.inner.write(&buf[i + 1..]) {
1037             Ok(i) => Ok(n + i),
1038             Err(_) => Ok(n),
1039         }
1040     }
1041
1042     // Vectored writes are very similar to the writes above, but adjusted for
1043     // the list of buffers that we have to write.
1044     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
1045         if self.need_flush {
1046             self.flush()?;
1047         }
1048
1049         // Find the last newline, and failing that write the whole buffer
1050         let last_newline = bufs.iter().enumerate().rev().find_map(|(i, buf)| {
1051             let pos = memchr::memrchr(b'\n', buf)?;
1052             Some((i, pos))
1053         });
1054         let (i, j) = match last_newline {
1055             Some(pair) => pair,
1056             None => return self.inner.write_vectored(bufs),
1057         };
1058         let (prefix, suffix) = bufs.split_at(i);
1059         let (buf, suffix) = suffix.split_at(1);
1060         let buf = &buf[0];
1061
1062         // Write everything up to the last newline, flushing afterwards. Note
1063         // that only if we finished our entire `write_vectored` do we try the
1064         // subsequent
1065         // `write`
1066         let mut n = 0;
1067         let prefix_amt = prefix.iter().map(|i| i.len()).sum();
1068         if prefix_amt > 0 {
1069             n += self.inner.write_vectored(prefix)?;
1070             self.need_flush = true;
1071         }
1072         if n == prefix_amt {
1073             match self.inner.write(&buf[..=j]) {
1074                 Ok(m) => n += m,
1075                 Err(e) if n == 0 => return Err(e),
1076                 Err(_) => return Ok(n),
1077             }
1078             self.need_flush = true;
1079         }
1080         if self.flush().is_err() || n != j + 1 + prefix_amt {
1081             return Ok(n);
1082         }
1083
1084         // ... and now write out everything remaining
1085         match self.inner.write(&buf[j + 1..]) {
1086             Ok(i) => n += i,
1087             Err(_) => return Ok(n),
1088         }
1089
1090         if suffix.iter().map(|s| s.len()).sum::<usize>() == 0 {
1091             return Ok(n);
1092         }
1093         match self.inner.write_vectored(suffix) {
1094             Ok(i) => Ok(n + i),
1095             Err(_) => Ok(n),
1096         }
1097     }
1098
1099     fn flush(&mut self) -> io::Result<()> {
1100         self.inner.flush()?;
1101         self.need_flush = false;
1102         Ok(())
1103     }
1104 }
1105
1106 #[stable(feature = "rust1", since = "1.0.0")]
1107 impl<W: Write> fmt::Debug for LineWriter<W>
1108 where
1109     W: fmt::Debug,
1110 {
1111     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1112         fmt.debug_struct("LineWriter")
1113             .field("writer", &self.inner.inner)
1114             .field(
1115                 "buffer",
1116                 &format_args!("{}/{}", self.inner.buf.len(), self.inner.buf.capacity()),
1117             )
1118             .finish()
1119     }
1120 }
1121
1122 #[cfg(test)]
1123 mod tests {
1124     use crate::io::prelude::*;
1125     use crate::io::{self, BufReader, BufWriter, IoSlice, LineWriter, SeekFrom};
1126     use crate::sync::atomic::{AtomicUsize, Ordering};
1127     use crate::thread;
1128
1129     /// A dummy reader intended at testing short-reads propagation.
1130     pub struct ShortReader {
1131         lengths: Vec<usize>,
1132     }
1133
1134     impl Read for ShortReader {
1135         fn read(&mut self, _: &mut [u8]) -> io::Result<usize> {
1136             if self.lengths.is_empty() { Ok(0) } else { Ok(self.lengths.remove(0)) }
1137         }
1138     }
1139
1140     #[test]
1141     fn test_buffered_reader() {
1142         let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4];
1143         let mut reader = BufReader::with_capacity(2, inner);
1144
1145         let mut buf = [0, 0, 0];
1146         let nread = reader.read(&mut buf);
1147         assert_eq!(nread.unwrap(), 3);
1148         assert_eq!(buf, [5, 6, 7]);
1149         assert_eq!(reader.buffer(), []);
1150
1151         let mut buf = [0, 0];
1152         let nread = reader.read(&mut buf);
1153         assert_eq!(nread.unwrap(), 2);
1154         assert_eq!(buf, [0, 1]);
1155         assert_eq!(reader.buffer(), []);
1156
1157         let mut buf = [0];
1158         let nread = reader.read(&mut buf);
1159         assert_eq!(nread.unwrap(), 1);
1160         assert_eq!(buf, [2]);
1161         assert_eq!(reader.buffer(), [3]);
1162
1163         let mut buf = [0, 0, 0];
1164         let nread = reader.read(&mut buf);
1165         assert_eq!(nread.unwrap(), 1);
1166         assert_eq!(buf, [3, 0, 0]);
1167         assert_eq!(reader.buffer(), []);
1168
1169         let nread = reader.read(&mut buf);
1170         assert_eq!(nread.unwrap(), 1);
1171         assert_eq!(buf, [4, 0, 0]);
1172         assert_eq!(reader.buffer(), []);
1173
1174         assert_eq!(reader.read(&mut buf).unwrap(), 0);
1175     }
1176
1177     #[test]
1178     fn test_buffered_reader_seek() {
1179         let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4];
1180         let mut reader = BufReader::with_capacity(2, io::Cursor::new(inner));
1181
1182         assert_eq!(reader.seek(SeekFrom::Start(3)).ok(), Some(3));
1183         assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..]));
1184         assert_eq!(reader.seek(SeekFrom::Current(0)).ok(), Some(3));
1185         assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..]));
1186         assert_eq!(reader.seek(SeekFrom::Current(1)).ok(), Some(4));
1187         assert_eq!(reader.fill_buf().ok(), Some(&[1, 2][..]));
1188         reader.consume(1);
1189         assert_eq!(reader.seek(SeekFrom::Current(-2)).ok(), Some(3));
1190     }
1191
1192     #[test]
1193     fn test_buffered_reader_seek_relative() {
1194         let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4];
1195         let mut reader = BufReader::with_capacity(2, io::Cursor::new(inner));
1196
1197         assert!(reader.seek_relative(3).is_ok());
1198         assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..]));
1199         assert!(reader.seek_relative(0).is_ok());
1200         assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..]));
1201         assert!(reader.seek_relative(1).is_ok());
1202         assert_eq!(reader.fill_buf().ok(), Some(&[1][..]));
1203         assert!(reader.seek_relative(-1).is_ok());
1204         assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..]));
1205         assert!(reader.seek_relative(2).is_ok());
1206         assert_eq!(reader.fill_buf().ok(), Some(&[2, 3][..]));
1207     }
1208
1209     #[test]
1210     fn test_buffered_reader_invalidated_after_read() {
1211         let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4];
1212         let mut reader = BufReader::with_capacity(3, io::Cursor::new(inner));
1213
1214         assert_eq!(reader.fill_buf().ok(), Some(&[5, 6, 7][..]));
1215         reader.consume(3);
1216
1217         let mut buffer = [0, 0, 0, 0, 0];
1218         assert_eq!(reader.read(&mut buffer).ok(), Some(5));
1219         assert_eq!(buffer, [0, 1, 2, 3, 4]);
1220
1221         assert!(reader.seek_relative(-2).is_ok());
1222         let mut buffer = [0, 0];
1223         assert_eq!(reader.read(&mut buffer).ok(), Some(2));
1224         assert_eq!(buffer, [3, 4]);
1225     }
1226
1227     #[test]
1228     fn test_buffered_reader_invalidated_after_seek() {
1229         let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4];
1230         let mut reader = BufReader::with_capacity(3, io::Cursor::new(inner));
1231
1232         assert_eq!(reader.fill_buf().ok(), Some(&[5, 6, 7][..]));
1233         reader.consume(3);
1234
1235         assert!(reader.seek(SeekFrom::Current(5)).is_ok());
1236
1237         assert!(reader.seek_relative(-2).is_ok());
1238         let mut buffer = [0, 0];
1239         assert_eq!(reader.read(&mut buffer).ok(), Some(2));
1240         assert_eq!(buffer, [3, 4]);
1241     }
1242
1243     #[test]
1244     fn test_buffered_reader_seek_underflow() {
1245         // gimmick reader that yields its position modulo 256 for each byte
1246         struct PositionReader {
1247             pos: u64,
1248         }
1249         impl Read for PositionReader {
1250             fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
1251                 let len = buf.len();
1252                 for x in buf {
1253                     *x = self.pos as u8;
1254                     self.pos = self.pos.wrapping_add(1);
1255                 }
1256                 Ok(len)
1257             }
1258         }
1259         impl Seek for PositionReader {
1260             fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
1261                 match pos {
1262                     SeekFrom::Start(n) => {
1263                         self.pos = n;
1264                     }
1265                     SeekFrom::Current(n) => {
1266                         self.pos = self.pos.wrapping_add(n as u64);
1267                     }
1268                     SeekFrom::End(n) => {
1269                         self.pos = u64::MAX.wrapping_add(n as u64);
1270                     }
1271                 }
1272                 Ok(self.pos)
1273             }
1274         }
1275
1276         let mut reader = BufReader::with_capacity(5, PositionReader { pos: 0 });
1277         assert_eq!(reader.fill_buf().ok(), Some(&[0, 1, 2, 3, 4][..]));
1278         assert_eq!(reader.seek(SeekFrom::End(-5)).ok(), Some(u64::MAX - 5));
1279         assert_eq!(reader.fill_buf().ok().map(|s| s.len()), Some(5));
1280         // the following seek will require two underlying seeks
1281         let expected = 9223372036854775802;
1282         assert_eq!(reader.seek(SeekFrom::Current(i64::MIN)).ok(), Some(expected));
1283         assert_eq!(reader.fill_buf().ok().map(|s| s.len()), Some(5));
1284         // seeking to 0 should empty the buffer.
1285         assert_eq!(reader.seek(SeekFrom::Current(0)).ok(), Some(expected));
1286         assert_eq!(reader.get_ref().pos, expected);
1287     }
1288
1289     #[test]
1290     fn test_buffered_reader_seek_underflow_discard_buffer_between_seeks() {
1291         // gimmick reader that returns Err after first seek
1292         struct ErrAfterFirstSeekReader {
1293             first_seek: bool,
1294         }
1295         impl Read for ErrAfterFirstSeekReader {
1296             fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
1297                 for x in &mut *buf {
1298                     *x = 0;
1299                 }
1300                 Ok(buf.len())
1301             }
1302         }
1303         impl Seek for ErrAfterFirstSeekReader {
1304             fn seek(&mut self, _: SeekFrom) -> io::Result<u64> {
1305                 if self.first_seek {
1306                     self.first_seek = false;
1307                     Ok(0)
1308                 } else {
1309                     Err(io::Error::new(io::ErrorKind::Other, "oh no!"))
1310                 }
1311             }
1312         }
1313
1314         let mut reader = BufReader::with_capacity(5, ErrAfterFirstSeekReader { first_seek: true });
1315         assert_eq!(reader.fill_buf().ok(), Some(&[0, 0, 0, 0, 0][..]));
1316
1317         // The following seek will require two underlying seeks.  The first will
1318         // succeed but the second will fail.  This should still invalidate the
1319         // buffer.
1320         assert!(reader.seek(SeekFrom::Current(i64::MIN)).is_err());
1321         assert_eq!(reader.buffer().len(), 0);
1322     }
1323
1324     #[test]
1325     fn test_buffered_writer() {
1326         let inner = Vec::new();
1327         let mut writer = BufWriter::with_capacity(2, inner);
1328
1329         writer.write(&[0, 1]).unwrap();
1330         assert_eq!(writer.buffer(), []);
1331         assert_eq!(*writer.get_ref(), [0, 1]);
1332
1333         writer.write(&[2]).unwrap();
1334         assert_eq!(writer.buffer(), [2]);
1335         assert_eq!(*writer.get_ref(), [0, 1]);
1336
1337         writer.write(&[3]).unwrap();
1338         assert_eq!(writer.buffer(), [2, 3]);
1339         assert_eq!(*writer.get_ref(), [0, 1]);
1340
1341         writer.flush().unwrap();
1342         assert_eq!(writer.buffer(), []);
1343         assert_eq!(*writer.get_ref(), [0, 1, 2, 3]);
1344
1345         writer.write(&[4]).unwrap();
1346         writer.write(&[5]).unwrap();
1347         assert_eq!(writer.buffer(), [4, 5]);
1348         assert_eq!(*writer.get_ref(), [0, 1, 2, 3]);
1349
1350         writer.write(&[6]).unwrap();
1351         assert_eq!(writer.buffer(), [6]);
1352         assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5]);
1353
1354         writer.write(&[7, 8]).unwrap();
1355         assert_eq!(writer.buffer(), []);
1356         assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8]);
1357
1358         writer.write(&[9, 10, 11]).unwrap();
1359         assert_eq!(writer.buffer(), []);
1360         assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
1361
1362         writer.flush().unwrap();
1363         assert_eq!(writer.buffer(), []);
1364         assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
1365     }
1366
1367     #[test]
1368     fn test_buffered_writer_inner_flushes() {
1369         let mut w = BufWriter::with_capacity(3, Vec::new());
1370         w.write(&[0, 1]).unwrap();
1371         assert_eq!(*w.get_ref(), []);
1372         let w = w.into_inner().unwrap();
1373         assert_eq!(w, [0, 1]);
1374     }
1375
1376     #[test]
1377     fn test_buffered_writer_seek() {
1378         let mut w = BufWriter::with_capacity(3, io::Cursor::new(Vec::new()));
1379         w.write_all(&[0, 1, 2, 3, 4, 5]).unwrap();
1380         w.write_all(&[6, 7]).unwrap();
1381         assert_eq!(w.seek(SeekFrom::Current(0)).ok(), Some(8));
1382         assert_eq!(&w.get_ref().get_ref()[..], &[0, 1, 2, 3, 4, 5, 6, 7][..]);
1383         assert_eq!(w.seek(SeekFrom::Start(2)).ok(), Some(2));
1384         w.write_all(&[8, 9]).unwrap();
1385         assert_eq!(&w.into_inner().unwrap().into_inner()[..], &[0, 1, 8, 9, 4, 5, 6, 7]);
1386     }
1387
1388     #[test]
1389     fn test_read_until() {
1390         let inner: &[u8] = &[0, 1, 2, 1, 0];
1391         let mut reader = BufReader::with_capacity(2, inner);
1392         let mut v = Vec::new();
1393         reader.read_until(0, &mut v).unwrap();
1394         assert_eq!(v, [0]);
1395         v.truncate(0);
1396         reader.read_until(2, &mut v).unwrap();
1397         assert_eq!(v, [1, 2]);
1398         v.truncate(0);
1399         reader.read_until(1, &mut v).unwrap();
1400         assert_eq!(v, [1]);
1401         v.truncate(0);
1402         reader.read_until(8, &mut v).unwrap();
1403         assert_eq!(v, [0]);
1404         v.truncate(0);
1405         reader.read_until(9, &mut v).unwrap();
1406         assert_eq!(v, []);
1407     }
1408
1409     #[test]
1410     fn test_line_buffer_fail_flush() {
1411         // Issue #32085
1412         struct FailFlushWriter<'a>(&'a mut Vec<u8>);
1413
1414         impl Write for FailFlushWriter<'_> {
1415             fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1416                 self.0.extend_from_slice(buf);
1417                 Ok(buf.len())
1418             }
1419             fn flush(&mut self) -> io::Result<()> {
1420                 Err(io::Error::new(io::ErrorKind::Other, "flush failed"))
1421             }
1422         }
1423
1424         let mut buf = Vec::new();
1425         {
1426             let mut writer = LineWriter::new(FailFlushWriter(&mut buf));
1427             let to_write = b"abc\ndef";
1428             if let Ok(written) = writer.write(to_write) {
1429                 assert!(written < to_write.len(), "didn't flush on new line");
1430                 // PASS
1431                 return;
1432             }
1433         }
1434         assert!(buf.is_empty(), "write returned an error but wrote data");
1435     }
1436
1437     #[test]
1438     fn test_line_buffer() {
1439         let mut writer = LineWriter::new(Vec::new());
1440         writer.write(&[0]).unwrap();
1441         assert_eq!(*writer.get_ref(), []);
1442         writer.write(&[1]).unwrap();
1443         assert_eq!(*writer.get_ref(), []);
1444         writer.flush().unwrap();
1445         assert_eq!(*writer.get_ref(), [0, 1]);
1446         writer.write(&[0, b'\n', 1, b'\n', 2]).unwrap();
1447         assert_eq!(*writer.get_ref(), [0, 1, 0, b'\n', 1, b'\n']);
1448         writer.flush().unwrap();
1449         assert_eq!(*writer.get_ref(), [0, 1, 0, b'\n', 1, b'\n', 2]);
1450         writer.write(&[3, b'\n']).unwrap();
1451         assert_eq!(*writer.get_ref(), [0, 1, 0, b'\n', 1, b'\n', 2, 3, b'\n']);
1452     }
1453
1454     #[test]
1455     fn test_read_line() {
1456         let in_buf: &[u8] = b"a\nb\nc";
1457         let mut reader = BufReader::with_capacity(2, in_buf);
1458         let mut s = String::new();
1459         reader.read_line(&mut s).unwrap();
1460         assert_eq!(s, "a\n");
1461         s.truncate(0);
1462         reader.read_line(&mut s).unwrap();
1463         assert_eq!(s, "b\n");
1464         s.truncate(0);
1465         reader.read_line(&mut s).unwrap();
1466         assert_eq!(s, "c");
1467         s.truncate(0);
1468         reader.read_line(&mut s).unwrap();
1469         assert_eq!(s, "");
1470     }
1471
1472     #[test]
1473     fn test_lines() {
1474         let in_buf: &[u8] = b"a\nb\nc";
1475         let reader = BufReader::with_capacity(2, in_buf);
1476         let mut it = reader.lines();
1477         assert_eq!(it.next().unwrap().unwrap(), "a".to_string());
1478         assert_eq!(it.next().unwrap().unwrap(), "b".to_string());
1479         assert_eq!(it.next().unwrap().unwrap(), "c".to_string());
1480         assert!(it.next().is_none());
1481     }
1482
1483     #[test]
1484     fn test_short_reads() {
1485         let inner = ShortReader { lengths: vec![0, 1, 2, 0, 1, 0] };
1486         let mut reader = BufReader::new(inner);
1487         let mut buf = [0, 0];
1488         assert_eq!(reader.read(&mut buf).unwrap(), 0);
1489         assert_eq!(reader.read(&mut buf).unwrap(), 1);
1490         assert_eq!(reader.read(&mut buf).unwrap(), 2);
1491         assert_eq!(reader.read(&mut buf).unwrap(), 0);
1492         assert_eq!(reader.read(&mut buf).unwrap(), 1);
1493         assert_eq!(reader.read(&mut buf).unwrap(), 0);
1494         assert_eq!(reader.read(&mut buf).unwrap(), 0);
1495     }
1496
1497     #[test]
1498     #[should_panic]
1499     fn dont_panic_in_drop_on_panicked_flush() {
1500         struct FailFlushWriter;
1501
1502         impl Write for FailFlushWriter {
1503             fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1504                 Ok(buf.len())
1505             }
1506             fn flush(&mut self) -> io::Result<()> {
1507                 Err(io::Error::last_os_error())
1508             }
1509         }
1510
1511         let writer = FailFlushWriter;
1512         let _writer = BufWriter::new(writer);
1513
1514         // If writer panics *again* due to the flush error then the process will
1515         // abort.
1516         panic!();
1517     }
1518
1519     #[test]
1520     #[cfg_attr(target_os = "emscripten", ignore)]
1521     fn panic_in_write_doesnt_flush_in_drop() {
1522         static WRITES: AtomicUsize = AtomicUsize::new(0);
1523
1524         struct PanicWriter;
1525
1526         impl Write for PanicWriter {
1527             fn write(&mut self, _: &[u8]) -> io::Result<usize> {
1528                 WRITES.fetch_add(1, Ordering::SeqCst);
1529                 panic!();
1530             }
1531             fn flush(&mut self) -> io::Result<()> {
1532                 Ok(())
1533             }
1534         }
1535
1536         thread::spawn(|| {
1537             let mut writer = BufWriter::new(PanicWriter);
1538             let _ = writer.write(b"hello world");
1539             let _ = writer.flush();
1540         })
1541         .join()
1542         .unwrap_err();
1543
1544         assert_eq!(WRITES.load(Ordering::SeqCst), 1);
1545     }
1546
1547     #[bench]
1548     fn bench_buffered_reader(b: &mut test::Bencher) {
1549         b.iter(|| BufReader::new(io::empty()));
1550     }
1551
1552     #[bench]
1553     fn bench_buffered_writer(b: &mut test::Bencher) {
1554         b.iter(|| BufWriter::new(io::sink()));
1555     }
1556
1557     struct AcceptOneThenFail {
1558         written: bool,
1559         flushed: bool,
1560     }
1561
1562     impl Write for AcceptOneThenFail {
1563         fn write(&mut self, data: &[u8]) -> io::Result<usize> {
1564             if !self.written {
1565                 assert_eq!(data, b"a\nb\n");
1566                 self.written = true;
1567                 Ok(data.len())
1568             } else {
1569                 Err(io::Error::new(io::ErrorKind::NotFound, "test"))
1570             }
1571         }
1572
1573         fn flush(&mut self) -> io::Result<()> {
1574             assert!(self.written);
1575             assert!(!self.flushed);
1576             self.flushed = true;
1577             Err(io::Error::new(io::ErrorKind::Other, "test"))
1578         }
1579     }
1580
1581     #[test]
1582     fn erroneous_flush_retried() {
1583         let a = AcceptOneThenFail { written: false, flushed: false };
1584
1585         let mut l = LineWriter::new(a);
1586         assert_eq!(l.write(b"a\nb\na").unwrap(), 4);
1587         assert!(l.get_ref().written);
1588         assert!(l.get_ref().flushed);
1589         l.get_mut().flushed = false;
1590
1591         assert_eq!(l.write(b"a").unwrap_err().kind(), io::ErrorKind::Other)
1592     }
1593
1594     #[test]
1595     fn line_vectored() {
1596         let mut a = LineWriter::new(Vec::new());
1597         assert_eq!(
1598             a.write_vectored(&[
1599                 IoSlice::new(&[]),
1600                 IoSlice::new(b"\n"),
1601                 IoSlice::new(&[]),
1602                 IoSlice::new(b"a"),
1603             ])
1604             .unwrap(),
1605             2,
1606         );
1607         assert_eq!(a.get_ref(), b"\n");
1608
1609         assert_eq!(
1610             a.write_vectored(&[
1611                 IoSlice::new(&[]),
1612                 IoSlice::new(b"b"),
1613                 IoSlice::new(&[]),
1614                 IoSlice::new(b"a"),
1615                 IoSlice::new(&[]),
1616                 IoSlice::new(b"c"),
1617             ])
1618             .unwrap(),
1619             3,
1620         );
1621         assert_eq!(a.get_ref(), b"\n");
1622         a.flush().unwrap();
1623         assert_eq!(a.get_ref(), b"\nabac");
1624         assert_eq!(a.write_vectored(&[]).unwrap(), 0);
1625         assert_eq!(
1626             a.write_vectored(&[
1627                 IoSlice::new(&[]),
1628                 IoSlice::new(&[]),
1629                 IoSlice::new(&[]),
1630                 IoSlice::new(&[]),
1631             ])
1632             .unwrap(),
1633             0,
1634         );
1635         assert_eq!(a.write_vectored(&[IoSlice::new(b"a\nb"),]).unwrap(), 3);
1636         assert_eq!(a.get_ref(), b"\nabaca\n");
1637     }
1638
1639     #[test]
1640     fn line_vectored_partial_and_errors() {
1641         enum Call {
1642             Write { inputs: Vec<&'static [u8]>, output: io::Result<usize> },
1643             Flush { output: io::Result<()> },
1644         }
1645         struct Writer {
1646             calls: Vec<Call>,
1647         }
1648
1649         impl Write for Writer {
1650             fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1651                 self.write_vectored(&[IoSlice::new(buf)])
1652             }
1653
1654             fn write_vectored(&mut self, buf: &[IoSlice<'_>]) -> io::Result<usize> {
1655                 match self.calls.pop().unwrap() {
1656                     Call::Write { inputs, output } => {
1657                         assert_eq!(inputs, buf.iter().map(|b| &**b).collect::<Vec<_>>());
1658                         output
1659                     }
1660                     _ => panic!("unexpected call to write"),
1661                 }
1662             }
1663
1664             fn flush(&mut self) -> io::Result<()> {
1665                 match self.calls.pop().unwrap() {
1666                     Call::Flush { output } => output,
1667                     _ => panic!("unexpected call to flush"),
1668                 }
1669             }
1670         }
1671
1672         impl Drop for Writer {
1673             fn drop(&mut self) {
1674                 if !thread::panicking() {
1675                     assert_eq!(self.calls.len(), 0);
1676                 }
1677             }
1678         }
1679
1680         // partial writes keep going
1681         let mut a = LineWriter::new(Writer { calls: Vec::new() });
1682         a.write_vectored(&[IoSlice::new(&[]), IoSlice::new(b"abc")]).unwrap();
1683         a.get_mut().calls.push(Call::Flush { output: Ok(()) });
1684         a.get_mut().calls.push(Call::Write { inputs: vec![b"bcx\n"], output: Ok(4) });
1685         a.get_mut().calls.push(Call::Write { inputs: vec![b"abcx\n"], output: Ok(1) });
1686         a.write_vectored(&[IoSlice::new(b"x"), IoSlice::new(b"\n")]).unwrap();
1687         a.get_mut().calls.push(Call::Flush { output: Ok(()) });
1688         a.flush().unwrap();
1689
1690         // erroneous writes stop and don't write more
1691         a.get_mut().calls.push(Call::Write { inputs: vec![b"x\n"], output: Err(err()) });
1692         assert_eq!(a.write_vectored(&[IoSlice::new(b"x"), IoSlice::new(b"\na")]).unwrap(), 2);
1693         a.get_mut().calls.push(Call::Flush { output: Ok(()) });
1694         a.get_mut().calls.push(Call::Write { inputs: vec![b"x\n"], output: Ok(2) });
1695         a.flush().unwrap();
1696
1697         fn err() -> io::Error {
1698             io::Error::new(io::ErrorKind::Other, "x")
1699         }
1700     }
1701 }