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