src/libstd/io/buffered.rs

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