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.
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.
11 //! Buffering wrappers for I/O traits
20 use io
::{self, DEFAULT_BUF_SIZE, Error, ErrorKind, SeekFrom}
;
22 /// The `BufReader` struct adds buffering to any reader.
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.
32 /// use std::io::prelude::*;
33 /// use std::io::BufReader;
34 /// use std::fs::File;
36 /// # fn foo() -> std::io::Result<()> {
37 /// let mut f = try!(File::open("log.txt"));
38 /// let mut reader = BufReader::new(f);
40 /// let mut line = String::new();
41 /// let len = try!(reader.read_line(&mut line));
42 /// println!("First line is {} bytes long", len);
46 #[stable(feature = "rust1", since = "1.0.0")]
47 pub struct BufReader
<R
> {
54 impl<R
: Read
> BufReader
<R
> {
55 /// Creates a new `BufReader` with a default buffer capacity.
60 /// use std::io::BufReader;
61 /// use std::fs::File;
63 /// # fn foo() -> std::io::Result<()> {
64 /// let mut f = try!(File::open("log.txt"));
65 /// let mut reader = BufReader::new(f);
69 #[stable(feature = "rust1", since = "1.0.0")]
70 pub fn new(inner
: R
) -> BufReader
<R
> {
71 BufReader
::with_capacity(DEFAULT_BUF_SIZE
, inner
)
74 /// Creates a new `BufReader` with the specified buffer capacity.
78 /// Creating a buffer with ten bytes of capacity:
81 /// use std::io::BufReader;
82 /// use std::fs::File;
84 /// # fn foo() -> std::io::Result<()> {
85 /// let mut f = try!(File::open("log.txt"));
86 /// let mut reader = BufReader::with_capacity(10, f);
90 #[stable(feature = "rust1", since = "1.0.0")]
91 pub fn with_capacity(cap
: usize, inner
: R
) -> BufReader
<R
> {
100 /// Gets a reference to the underlying reader.
102 /// It is inadvisable to directly read from the underlying reader.
107 /// use std::io::BufReader;
108 /// use std::fs::File;
110 /// # fn foo() -> std::io::Result<()> {
111 /// let mut f1 = try!(File::open("log.txt"));
112 /// let mut reader = BufReader::new(f1);
114 /// let f2 = reader.get_ref();
118 #[stable(feature = "rust1", since = "1.0.0")]
119 pub fn get_ref(&self) -> &R { &self.inner }
121 /// Gets a mutable reference to the underlying reader.
123 /// It is inadvisable to directly read from the underlying reader.
128 /// use std::io::BufReader;
129 /// use std::fs::File;
131 /// # fn foo() -> std::io::Result<()> {
132 /// let mut f1 = try!(File::open("log.txt"));
133 /// let mut reader = BufReader::new(f1);
135 /// let f2 = reader.get_mut();
139 #[stable(feature = "rust1", since = "1.0.0")]
140 pub fn get_mut(&mut self) -> &mut R { &mut self.inner }
142 /// Unwraps this `BufReader`, returning the underlying reader.
144 /// Note that any leftover data in the internal buffer is lost.
149 /// use std::io::BufReader;
150 /// use std::fs::File;
152 /// # fn foo() -> std::io::Result<()> {
153 /// let mut f1 = try!(File::open("log.txt"));
154 /// let mut reader = BufReader::new(f1);
156 /// let f2 = reader.into_inner();
160 #[stable(feature = "rust1", since = "1.0.0")]
161 pub fn into_inner(self) -> R { self.inner }
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
170 if self.pos
== self.cap
&& buf
.len() >= self.buf
.len() {
171 return self.inner
.read(buf
);
174 let mut rem
= try
!(self.fill_buf());
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
));
191 Ok(&self.buf
[self.pos
..self.cap
])
194 fn consume(&mut self, amt
: usize) {
195 self.pos
= cmp
::min(self.pos
+ amt
, self.cap
);
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()))
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.
213 /// The position used for seeking with `SeekFrom::Current(_)` is the
214 /// position the underlying reader would be at if the `BufReader` had no
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.
222 /// See `std::io::Seek` for more details.
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> {
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
238 if let Some(offset
) = n
.checked_sub(remainder
) {
239 result
= try
!(self.inner
.seek(SeekFrom
::Current(offset
)));
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
)));
247 // Seeking with Start/End doesn't care about our buffer length.
248 result
= try
!(self.inner
.seek(pos
));
250 self.pos
= self.cap
; // empty the buffer
255 /// Wraps a writer and buffers its output.
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.
262 /// The buffer will be written out when the writer is dropped.
266 /// Let's write the numbers one through ten to a `TcpStream`:
269 /// use std::io::prelude::*;
270 /// use std::net::TcpStream;
272 /// let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();
275 /// stream.write(&[i]).unwrap();
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
284 /// use std::io::prelude::*;
285 /// use std::io::BufWriter;
286 /// use std::net::TcpStream;
288 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
291 /// stream.write(&[i]).unwrap();
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
> {
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.
311 /// use std::io::BufWriter;
312 /// use std::net::TcpStream;
314 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
316 /// // do stuff with the stream
318 /// // we want to get our `TcpStream` back, so let's try:
320 /// let stream = match stream.into_inner() {
323 /// // Here, e is an IntoInnerError
324 /// panic!("An error occurred");
329 #[stable(feature = "rust1", since = "1.0.0")]
330 pub struct IntoInnerError
<W
>(W
, Error
);
332 impl<W
: Write
> BufWriter
<W
> {
333 /// Creates a new `BufWriter` with a default buffer capacity.
338 /// use std::io::BufWriter;
339 /// use std::net::TcpStream;
341 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
343 #[stable(feature = "rust1", since = "1.0.0")]
344 pub fn new(inner
: W
) -> BufWriter
<W
> {
345 BufWriter
::with_capacity(DEFAULT_BUF_SIZE
, inner
)
348 /// Creates a new `BufWriter` with the specified buffer capacity.
352 /// Creating a buffer with a buffer of a hundred bytes.
355 /// use std::io::BufWriter;
356 /// use std::net::TcpStream;
358 /// let stream = TcpStream::connect("127.0.0.1:34254").unwrap();
359 /// let mut buffer = BufWriter::with_capacity(100, stream);
361 #[stable(feature = "rust1", since = "1.0.0")]
362 pub fn with_capacity(cap
: usize, inner
: W
) -> BufWriter
<W
> {
365 buf
: Vec
::with_capacity(cap
),
369 fn flush_buf(&mut self) -> io
::Result
<()> {
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
..]) {
376 ret
= Err(Error
::new(ErrorKind
::WriteZero
,
377 "failed to write the buffered data"));
380 Ok(n
) => written
+= n
,
381 Err(ref e
) if e
.kind() == io
::ErrorKind
::Interrupted
=> {}
382 Err(e
) => { ret = Err(e); break }
387 self.buf
.drain(..written
);
392 /// Gets a reference to the underlying writer.
397 /// use std::io::BufWriter;
398 /// use std::net::TcpStream;
400 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
402 /// // we can use reference just like buffer
403 /// let reference = buffer.get_ref();
405 #[stable(feature = "rust1", since = "1.0.0")]
406 pub fn get_ref(&self) -> &W { self.inner.as_ref().unwrap() }
408 /// Gets a mutable reference to the underlying writer.
410 /// It is inadvisable to directly write to the underlying writer.
415 /// use std::io::BufWriter;
416 /// use std::net::TcpStream;
418 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
420 /// // we can use reference just like buffer
421 /// let reference = buffer.get_mut();
423 #[stable(feature = "rust1", since = "1.0.0")]
424 pub fn get_mut(&mut self) -> &mut W { self.inner.as_mut().unwrap() }
426 /// Unwraps this `BufWriter`, returning the underlying writer.
428 /// The buffer is written out before returning the writer.
433 /// use std::io::BufWriter;
434 /// use std::net::TcpStream;
436 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
438 /// // unwrap the TcpStream and flush the buffer
439 /// let stream = buffer.into_inner().unwrap();
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())
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());
456 if buf
.len() >= self.buf
.capacity() {
457 self.inner
.as_mut().unwrap().write(buf
)
459 let amt
= cmp
::min(buf
.len(), self.buf
.capacity());
460 Write
::write(&mut self.buf
, &buf
[..amt
])
463 fn flush(&mut self) -> io
::Result
<()> {
464 self.flush_buf().and_then(|()| self.get_mut().flush())
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()))
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.
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
))
488 impl<W
: Write
> Drop
for BufWriter
<W
> {
490 if self.inner
.is_some() {
491 // dtors should not panic, so we ignore a failed flush
492 let _r
= self.flush_buf();
497 impl<W
> IntoInnerError
<W
> {
498 /// Returns the error which caused the call to `into_inner()` to fail.
500 /// This error was returned when attempting to write the internal buffer.
505 /// use std::io::BufWriter;
506 /// use std::net::TcpStream;
508 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
510 /// // do stuff with the stream
512 /// // we want to get our `TcpStream` back, so let's try:
514 /// let stream = match stream.into_inner() {
517 /// // Here, e is an IntoInnerError, let's log the inner error.
519 /// // We'll just 'log' to stdout for this example.
520 /// println!("{}", e.error());
522 /// panic!("An unexpected error occurred.");
526 #[stable(feature = "rust1", since = "1.0.0")]
527 pub fn error(&self) -> &Error { &self.1 }
529 /// Returns the buffered writer instance which generated the error.
531 /// The returned object can be used for error recovery, such as
532 /// re-inspecting the buffer.
537 /// use std::io::BufWriter;
538 /// use std::net::TcpStream;
540 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
542 /// // do stuff with the stream
544 /// // we want to get our `TcpStream` back, so let's try:
546 /// let stream = match stream.into_inner() {
549 /// // Here, e is a IntoInnerError, let's re-examine the buffer:
550 /// let buffer = e.into_inner();
552 /// // do stuff to try to recover
554 /// // afterwards, let's just return the stream
555 /// buffer.into_inner().unwrap()
559 #[stable(feature = "rust1", since = "1.0.0")]
560 pub fn into_inner(self) -> W { self.0 }
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 }
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())
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
{
582 /// Wraps a writer and buffers output to it, flushing whenever a newline
583 /// (`0x0a`, `'\n'`) is detected.
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.
591 /// [bufwriter]: struct.BufWriter.html
593 /// If there's still a partial line in the buffer when the `LineWriter` is
594 /// dropped, it will flush those contents.
598 /// We can use `LineWriter` to write one line at a time, significantly
599 /// reducing the number of actual writes to the file.
602 /// use std::fs::File;
603 /// use std::io::prelude::*;
604 /// use std::io::LineWriter;
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.";
613 /// let file = try!(File::create("poem.txt"));
614 /// let mut file = LineWriter::new(file);
616 /// for &byte in road_not_taken.iter() {
617 /// file.write(&[byte]).unwrap();
620 /// // let's check we did the right thing.
621 /// let mut file = try!(File::open("poem.txt"));
622 /// let mut contents = String::new();
624 /// try!(file.read_to_string(&mut contents));
626 /// assert_eq!(contents.as_bytes(), &road_not_taken[..]);
630 #[stable(feature = "rust1", since = "1.0.0")]
631 pub struct LineWriter
<W
: Write
> {
635 impl<W
: Write
> LineWriter
<W
> {
636 /// Creates a new `LineWriter`.
641 /// use std::fs::File;
642 /// use std::io::LineWriter;
644 /// # fn foo() -> std::io::Result<()> {
645 /// let file = try!(File::create("poem.txt"));
646 /// let file = LineWriter::new(file);
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
)
656 /// Creates a new `LineWriter` with a specified capacity for the internal
662 /// use std::fs::File;
663 /// use std::io::LineWriter;
665 /// # fn foo() -> std::io::Result<()> {
666 /// let file = try!(File::create("poem.txt"));
667 /// let file = LineWriter::with_capacity(100, file);
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) }
676 /// Gets a reference to the underlying writer.
681 /// use std::fs::File;
682 /// use std::io::LineWriter;
684 /// # fn foo() -> std::io::Result<()> {
685 /// let file = try!(File::create("poem.txt"));
686 /// let file = LineWriter::new(file);
688 /// let reference = file.get_ref();
692 #[stable(feature = "rust1", since = "1.0.0")]
693 pub fn get_ref(&self) -> &W { self.inner.get_ref() }
695 /// Gets a mutable reference to the underlying writer.
697 /// Caution must be taken when calling methods on the mutable reference
698 /// returned as extra writes could corrupt the output stream.
703 /// use std::fs::File;
704 /// use std::io::LineWriter;
706 /// # fn foo() -> std::io::Result<()> {
707 /// let file = try!(File::create("poem.txt"));
708 /// let mut file = LineWriter::new(file);
710 /// // we can use reference just like file
711 /// let reference = file.get_mut();
715 #[stable(feature = "rust1", since = "1.0.0")]
716 pub fn get_mut(&mut self) -> &mut W { self.inner.get_mut() }
718 /// Unwraps this `LineWriter`, returning the underlying writer.
720 /// The internal buffer is written out before returning the writer.
725 /// use std::fs::File;
726 /// use std::io::LineWriter;
728 /// # fn foo() -> std::io::Result<()> {
729 /// let file = try!(File::create("poem.txt"));
731 /// let writer: LineWriter<File> = LineWriter::new(file);
733 /// let file: File = try!(writer.into_inner());
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
)
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'
) {
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
)
755 None
=> self.inner
.write(buf
),
759 fn flush(&mut self) -> io
::Result
<()> { self.inner.flush() }
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
)
768 &format_args
!("{}/{}", self.inner
.buf
.len(), self.inner
.buf
.capacity()))
773 struct InternalBufWriter
<W
: Write
>(BufWriter
<W
>);
775 impl<W
: Read
+ Write
> InternalBufWriter
<W
> {
776 fn get_mut(&mut self) -> &mut BufWriter
<W
> {
777 let InternalBufWriter(ref mut w
) = *self;
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
)
788 /// Wraps a Stream and buffers input and output to and from it.
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`.
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
>>
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")]
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
)
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 }
822 /// Creates a new buffered stream with the default reader/writer buffer
824 pub fn new(inner
: S
) -> BufStream
<S
> {
825 BufStream
::with_capacities(DEFAULT_BUF_SIZE
, DEFAULT_BUF_SIZE
, inner
)
828 /// Gets a reference to the underlying stream.
829 pub fn get_ref(&self) -> &S
{
830 let InternalBufWriter(ref w
) = self.inner
.inner
;
834 /// Gets a mutable reference to the underlying stream.
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
;
843 /// Unwraps this `BufStream`, returning the underlying stream.
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 }
,
857 #[unstable(feature = "buf_stream",
858 reason
= "unsure about semantics of buffering two directions, \
859 leading to issues like #17136")]
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) }
866 #[unstable(feature = "buf_stream",
867 reason
= "unsure about semantics of buffering two directions, \
868 leading to issues like #17136")]
870 impl<S
: Read
+ Write
> Read
for BufStream
<S
> {
871 fn read(&mut self, buf
: &mut [u8]) -> io
::Result
<usize> {
876 #[unstable(feature = "buf_stream",
877 reason
= "unsure about semantics of buffering two directions, \
878 leading to issues like #17136")]
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
)
884 fn flush(&mut self) -> io
::Result
<()> {
885 self.inner
.inner
.get_mut().flush()
889 #[unstable(feature = "buf_stream",
890 reason
= "unsure about semantics of buffering two directions, \
891 leading to issues like #17136")]
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()))
910 use io
::{self, BufReader, BufWriter, BufStream, Cursor, LineWriter, SeekFrom}
;
913 /// A dummy reader intended at testing short-reads propagation.
914 pub struct ShortReader
{
918 impl Read
for ShortReader
{
919 fn read(&mut self, _
: &mut [u8]) -> io
::Result
<usize> {
920 if self.lengths
.is_empty() {
923 Ok(self.lengths
.remove(0))
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
);
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];
939 let mut buf
= [0, 0];
940 let nread
= reader
.read(&mut buf
);
941 assert_eq
!(nread
.unwrap(), 2);
942 let b
: &[_
] = &[0, 1];
946 let nread
= reader
.read(&mut buf
);
947 assert_eq
!(nread
.unwrap(), 1);
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];
957 let nread
= reader
.read(&mut buf
);
958 assert_eq
!(nread
.unwrap(), 1);
959 let b
: &[_
] = &[4, 0, 0];
962 assert_eq
!(reader
.read(&mut buf
).unwrap(), 0);
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
));
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][..]));
977 assert_eq
!(reader
.seek(SeekFrom
::Current(-2)).ok(), Some(3));
981 fn test_buffered_reader_seek_underflow() {
982 // gimmick reader that yields its position modulo 256 for each byte
983 struct PositionReader
{
986 impl Read
for PositionReader
{
987 fn read(&mut self, buf
: &mut [u8]) -> io
::Result
<usize> {
991 self.pos
= self.pos
.wrapping_add(1);
996 impl Seek
for PositionReader
{
997 fn seek(&mut self, pos
: SeekFrom
) -> io
::Result
<u64> {
999 SeekFrom
::Start(n
) => {
1002 SeekFrom
::Current(n
) => {
1003 self.pos
= self.pos
.wrapping_add(n
as u64);
1005 SeekFrom
::End(n
) => {
1006 self.pos
= u64::max_value().wrapping_add(n
as u64);
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
);
1027 fn test_buffered_writer() {
1028 let inner
= Vec
::new();
1029 let mut writer
= BufWriter
::with_capacity(2, inner
);
1031 writer
.write(&[0, 1]).unwrap();
1032 assert_eq
!(*writer
.get_ref(), [0, 1]);
1034 writer
.write(&[2]).unwrap();
1035 assert_eq
!(*writer
.get_ref(), [0, 1]);
1037 writer
.write(&[3]).unwrap();
1038 assert_eq
!(*writer
.get_ref(), [0, 1]);
1040 writer
.flush().unwrap();
1041 assert_eq
!(*writer
.get_ref(), [0, 1, 2, 3]);
1043 writer
.write(&[4]).unwrap();
1044 writer
.write(&[5]).unwrap();
1045 assert_eq
!(*writer
.get_ref(), [0, 1, 2, 3]);
1047 writer
.write(&[6]).unwrap();
1048 assert_eq
!(*writer
.get_ref(), [0, 1, 2, 3, 4, 5]);
1050 writer
.write(&[7, 8]).unwrap();
1051 assert_eq
!(*writer
.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8]);
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]);
1056 writer
.flush().unwrap();
1057 assert_eq
!(*writer
.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
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]);
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]);
1081 // This is just here to make sure that we don't infinite loop in the
1082 // newtype struct autoderef weirdness
1084 fn test_buffered_stream() {
1088 fn write(&mut self, b
: &[u8]) -> io
::Result
<usize> { Ok(b.len()) }
1089 fn flush(&mut self) -> io
::Result
<()> { Ok(()) }
1093 fn read(&mut self, _
: &mut [u8]) -> io
::Result
<usize> { Ok(0) }
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();
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();
1110 reader
.read_until(2, &mut v
).unwrap();
1111 assert_eq
!(v
, [1, 2]);
1113 reader
.read_until(1, &mut v
).unwrap();
1116 reader
.read_until(8, &mut v
).unwrap();
1119 reader
.read_until(9, &mut v
).unwrap();
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'
]);
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");
1148 reader
.read_line(&mut s
).unwrap();
1149 assert_eq
!(s
, "b\n");
1151 reader
.read_line(&mut s
).unwrap();
1154 reader
.read_line(&mut s
).unwrap();
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());
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);
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(), 'ß'
);
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());
1202 fn dont_panic_in_drop_on_panicked_flush() {
1203 struct FailFlushWriter
;
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())
1212 let writer
= FailFlushWriter
;
1213 let _writer
= BufWriter
::new(writer
);
1215 // If writer panics *again* due to the flush error then the process will
1221 fn bench_buffered_reader(b
: &mut test
::Bencher
) {
1223 BufReader
::new(io
::empty())
1228 fn bench_buffered_writer(b
: &mut test
::Bencher
) {
1230 BufWriter
::new(io
::sink())
1235 fn bench_buffered_stream(b
: &mut test
::Bencher
) {
1236 let mut buf
= Cursor
::new(Vec
::new());
1238 BufStream
::new(&mut buf
);