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