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