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