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