1 // Copyright 2015 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 //! Traits, helpers, and type definitions for core I/O functionality.
13 #![stable(feature = "rust1", since = "1.0.0")]
16 use rustc_unicode::str as core_str;
17 use error as std_error;
21 use ops::{Drop, FnOnce};
22 use option::Option::{self, Some, None};
23 use result::Result::{Ok, Err};
29 pub use self::buffered::{BufReader, BufWriter, BufStream, LineWriter};
30 pub use self::buffered::IntoInnerError;
31 pub use self::cursor::Cursor;
32 pub use self::error::{Result, Error, ErrorKind};
33 pub use self::util::{copy, sink, Sink, empty, Empty, repeat, Repeat};
34 pub use self::stdio::{stdin, stdout, stderr, _print, Stdin, Stdout, Stderr};
35 pub use self::stdio::{StdoutLock, StderrLock, StdinLock};
36 #[doc(no_inline, hidden)]
37 pub use self::stdio::{set_panic, set_print};
48 const DEFAULT_BUF_SIZE: usize = 64 * 1024;
50 // A few methods below (read_to_string, read_line) will append data into a
51 // `String` buffer, but we need to be pretty careful when doing this. The
52 // implementation will just call `.as_mut_vec()` and then delegate to a
53 // byte-oriented reading method, but we must ensure that when returning we never
54 // leave `buf` in a state such that it contains invalid UTF-8 in its bounds.
56 // To this end, we use an RAII guard (to protect against panics) which updates
57 // the length of the string when it is dropped. This guard initially truncates
58 // the string to the prior length and only after we've validated that the
59 // new contents are valid UTF-8 do we allow it to set a longer length.
61 // The unsafety in this function is twofold:
63 // 1. We're looking at the raw bytes of `buf`, so we take on the burden of UTF-8
65 // 2. We're passing a raw buffer to the function `f`, and it is expected that
66 // the function only *appends* bytes to the buffer. We'll get undefined
67 // behavior if existing bytes are overwritten to have non-UTF-8 data.
68 fn append_to_string<F>(buf: &mut String, f: F) -> Result<usize>
69 where F: FnOnce(&mut Vec<u8>) -> Result<usize>
71 struct Guard<'a> { s: &'a mut Vec<u8>, len: usize }
72 impl<'a> Drop for Guard<'a> {
74 unsafe { self.s.set_len(self.len); }
79 let mut g = Guard { len: buf.len(), s: buf.as_mut_vec() };
81 if str::from_utf8(&g.s[g.len..]).is_err() {
83 Err(Error::new(ErrorKind::InvalidData,
84 "stream did not contain valid UTF-8"))
93 // This uses an adaptive system to extend the vector when it fills. We want to
94 // avoid paying to allocate and zero a huge chunk of memory if the reader only
95 // has 4 bytes while still making large reads if the reader does have a ton
96 // of data to return. Simply tacking on an extra DEFAULT_BUF_SIZE space every
97 // time is 4,500 times (!) slower than this if the reader has a very small
98 // amount of data to return.
99 fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize> {
100 let start_len = buf.len();
101 let mut len = start_len;
102 let mut new_write_size = 16;
105 if len == buf.len() {
106 if new_write_size < DEFAULT_BUF_SIZE {
109 buf.resize(len + new_write_size, 0);
112 match r.read(&mut buf[len..]) {
114 ret = Ok(len - start_len);
118 Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
130 /// The `Read` trait allows for reading bytes from a source.
132 /// Implementors of the `Read` trait are sometimes called 'readers'.
134 /// Readers are defined by one required method, `read()`. Each call to `read`
135 /// will attempt to pull bytes from this source into a provided buffer. A
136 /// number of other methods are implemented in terms of `read()`, giving
137 /// implementors a number of ways to read bytes while only needing to implement
140 /// Readers are intended to be composable with one another. Many implementors
141 /// throughout `std::io` take and provide types which implement the `Read`
146 /// [`File`][file]s implement `Read`:
148 /// [file]: ../std/fs/struct.File.html
152 /// use std::fs::File;
153 /// use std::io::Read;
155 /// # fn foo() -> io::Result<()> {
156 /// let mut f = try!(File::open("foo.txt"));
157 /// let mut buffer = Vec::new();
159 /// // read some bytes
160 /// f.read(&mut buffer).unwrap();
162 /// // read the whole file
163 /// f.read_to_end(&mut buffer).unwrap();
165 /// // read into a String, so that you don't need to do the conversion.
166 /// let mut buffer = String::new();
167 /// f.read_to_string(&mut buffer).unwrap();
169 /// // and more! See the other methods for more details.
173 #[stable(feature = "rust1", since = "1.0.0")]
175 /// Pull some bytes from this source into the specified buffer, returning
176 /// how many bytes were read.
178 /// This function does not provide any guarantees about whether it blocks
179 /// waiting for data, but if an object needs to block for a read but cannot
180 /// it will typically signal this via an `Err` return value.
182 /// If the return value of this method is `Ok(n)`, then it must be
183 /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
184 /// that the buffer `buf` has been filled in with `n` bytes of data from this
185 /// source. If `n` is `0`, then it can indicate one of two scenarios:
187 /// 1. This reader has reached its "end of file" and will likely no longer
188 /// be able to produce bytes. Note that this does not mean that the
189 /// reader will *always* no longer be able to produce bytes.
190 /// 2. The buffer specified was 0 bytes in length.
192 /// No guarantees are provided about the contents of `buf` when this
193 /// function is called, implementations cannot rely on any property of the
194 /// contents of `buf` being true. It is recommended that implementations
195 /// only write data to `buf` instead of reading its contents.
199 /// If this function encounters any form of I/O or other error, an error
200 /// variant will be returned. If an error is returned then it must be
201 /// guaranteed that no bytes were read.
205 /// [`File`][file]s implement `Read`:
207 /// [file]: ../std/fs/struct.File.html
211 /// use std::io::prelude::*;
212 /// use std::fs::File;
214 /// # fn foo() -> io::Result<()> {
215 /// let mut f = try!(File::open("foo.txt"));
216 /// let mut buffer = [0; 10];
219 /// try!(f.read(&mut buffer[..]));
223 #[stable(feature = "rust1", since = "1.0.0")]
224 fn read(&mut self, buf: &mut [u8]) -> Result<usize>;
226 /// Read all bytes until EOF in this source, placing them into `buf`.
228 /// All bytes read from this source will be appended to the specified buffer
229 /// `buf`. This function will continuously call `read` to append more data to
230 /// `buf` until `read` returns either `Ok(0)` or an error of
231 /// non-`ErrorKind::Interrupted` kind.
233 /// If successful, this function will return the total number of bytes read.
237 /// If this function encounters an error of the kind
238 /// `ErrorKind::Interrupted` then the error is ignored and the operation
241 /// If any other read error is encountered then this function immediately
242 /// returns. Any bytes which have already been read will be appended to
247 /// [`File`][file]s implement `Read`:
249 /// [file]: ../std/fs/struct.File.html
253 /// use std::io::prelude::*;
254 /// use std::fs::File;
256 /// # fn foo() -> io::Result<()> {
257 /// let mut f = try!(File::open("foo.txt"));
258 /// let mut buffer = Vec::new();
260 /// // read the whole file
261 /// try!(f.read_to_end(&mut buffer));
265 #[stable(feature = "rust1", since = "1.0.0")]
266 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
267 read_to_end(self, buf)
270 /// Read all bytes until EOF in this source, placing them into `buf`.
272 /// If successful, this function returns the number of bytes which were read
273 /// and appended to `buf`.
277 /// If the data in this stream is *not* valid UTF-8 then an error is
278 /// returned and `buf` is unchanged.
280 /// See [`read_to_end()`][readtoend] for other error semantics.
282 /// [readtoend]: #method.read_to_end
286 /// [`File`][file]s implement `Read`:
288 /// [file]: ../std/fs/struct.File.html
292 /// use std::io::prelude::*;
293 /// use std::fs::File;
295 /// # fn foo() -> io::Result<()> {
296 /// let mut f = try!(File::open("foo.txt"));
297 /// let mut buffer = String::new();
299 /// try!(f.read_to_string(&mut buffer));
303 #[stable(feature = "rust1", since = "1.0.0")]
304 fn read_to_string(&mut self, buf: &mut String) -> Result<usize> {
305 // Note that we do *not* call `.read_to_end()` here. We are passing
306 // `&mut Vec<u8>` (the raw contents of `buf`) into the `read_to_end`
307 // method to fill it up. An arbitrary implementation could overwrite the
308 // entire contents of the vector, not just append to it (which is what
309 // we are expecting).
311 // To prevent extraneously checking the UTF-8-ness of the entire buffer
312 // we pass it to our hardcoded `read_to_end` implementation which we
313 // know is guaranteed to only read data into the end of the buffer.
314 append_to_string(buf, |b| read_to_end(self, b))
317 /// Creates a "by reference" adaptor for this instance of `Read`.
319 /// The returned adaptor also implements `Read` and will simply borrow this
324 /// [`File`][file]s implement `Read`:
326 /// [file]: ../std/fs/struct.File.html
330 /// use std::io::Read;
331 /// use std::fs::File;
333 /// # fn foo() -> io::Result<()> {
334 /// let mut f = try!(File::open("foo.txt"));
335 /// let mut buffer = Vec::new();
336 /// let mut other_buffer = Vec::new();
339 /// let reference = f.by_ref();
341 /// // read at most 5 bytes
342 /// try!(reference.take(5).read_to_end(&mut buffer));
344 /// } // drop our &mut reference so we can use f again
346 /// // original file still usable, read the rest
347 /// try!(f.read_to_end(&mut other_buffer));
351 #[stable(feature = "rust1", since = "1.0.0")]
352 fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
354 /// Transforms this `Read` instance to an `Iterator` over its bytes.
356 /// The returned type implements `Iterator` where the `Item` is `Result<u8,
357 /// R::Err>`. The yielded item is `Ok` if a byte was successfully read and
358 /// `Err` otherwise for I/O errors. EOF is mapped to returning `None` from
363 /// [`File`][file]s implement `Read`:
365 /// [file]: ../std/fs/struct.File.html
369 /// use std::io::prelude::*;
370 /// use std::fs::File;
372 /// # fn foo() -> io::Result<()> {
373 /// let mut f = try!(File::open("foo.txt"));
375 /// for byte in f.bytes() {
376 /// println!("{}", byte.unwrap());
381 #[stable(feature = "rust1", since = "1.0.0")]
382 fn bytes(self) -> Bytes<Self> where Self: Sized {
383 Bytes { inner: self }
386 /// Transforms this `Read` instance to an `Iterator` over `char`s.
388 /// This adaptor will attempt to interpret this reader as a UTF-8 encoded
389 /// sequence of characters. The returned iterator will return `None` once
390 /// EOF is reached for this reader. Otherwise each element yielded will be a
391 /// `Result<char, E>` where `E` may contain information about what I/O error
392 /// occurred or where decoding failed.
394 /// Currently this adaptor will discard intermediate data read, and should
395 /// be avoided if this is not desired.
399 /// [`File`][file]s implement `Read`:
401 /// [file]: ../std/fs/struct.File.html
406 /// use std::io::prelude::*;
407 /// use std::fs::File;
409 /// # fn foo() -> io::Result<()> {
410 /// let mut f = try!(File::open("foo.txt"));
412 /// for c in f.chars() {
413 /// println!("{}", c.unwrap());
418 #[unstable(feature = "io", reason = "the semantics of a partial read/write \
419 of where errors happen is currently \
420 unclear and may change")]
421 fn chars(self) -> Chars<Self> where Self: Sized {
422 Chars { inner: self }
425 /// Creates an adaptor which will chain this stream with another.
427 /// The returned `Read` instance will first read all bytes from this object
428 /// until EOF is encountered. Afterwards the output is equivalent to the
429 /// output of `next`.
433 /// [`File`][file]s implement `Read`:
435 /// [file]: ../std/fs/struct.File.html
439 /// use std::io::prelude::*;
440 /// use std::fs::File;
442 /// # fn foo() -> io::Result<()> {
443 /// let mut f1 = try!(File::open("foo.txt"));
444 /// let mut f2 = try!(File::open("bar.txt"));
446 /// let mut handle = f1.chain(f2);
447 /// let mut buffer = String::new();
449 /// // read the value into a String. We could use any Read method here,
450 /// // this is just one example.
451 /// try!(handle.read_to_string(&mut buffer));
455 #[stable(feature = "rust1", since = "1.0.0")]
456 fn chain<R: Read>(self, next: R) -> Chain<Self, R> where Self: Sized {
457 Chain { first: self, second: next, done_first: false }
460 /// Creates an adaptor which will read at most `limit` bytes from it.
462 /// This function returns a new instance of `Read` which will read at most
463 /// `limit` bytes, after which it will always return EOF (`Ok(0)`). Any
464 /// read errors will not count towards the number of bytes read and future
465 /// calls to `read` may succeed.
469 /// [`File`][file]s implement `Read`:
471 /// [file]: ../std/fs/struct.File.html
475 /// use std::io::prelude::*;
476 /// use std::fs::File;
478 /// # fn foo() -> io::Result<()> {
479 /// let mut f = try!(File::open("foo.txt"));
480 /// let mut buffer = [0; 10];
482 /// // read at most five bytes
483 /// let mut handle = f.take(5);
485 /// try!(handle.read(&mut buffer));
489 #[stable(feature = "rust1", since = "1.0.0")]
490 fn take(self, limit: u64) -> Take<Self> where Self: Sized {
491 Take { inner: self, limit: limit }
494 /// Creates a reader adaptor which will write all read data into the given
497 /// Whenever the returned `Read` instance is read it will write the read
498 /// data to `out`. The current semantics of this implementation imply that
499 /// a `write` error will not report how much data was initially read.
503 /// [`File`][file]s implement `Read`:
505 /// [file]: ../std/fs/struct.File.html
510 /// use std::io::prelude::*;
511 /// use std::fs::File;
513 /// # fn foo() -> io::Result<()> {
514 /// let mut f = try!(File::open("foo.txt"));
515 /// let mut buffer1 = Vec::with_capacity(10);
516 /// let mut buffer2 = Vec::with_capacity(10);
518 /// // write the output to buffer1 as we read
519 /// let mut handle = f.tee(&mut buffer1);
521 /// try!(handle.read(&mut buffer2));
525 #[unstable(feature = "io", reason = "the semantics of a partial read/write \
526 of where errors happen is currently \
527 unclear and may change")]
528 fn tee<W: Write>(self, out: W) -> Tee<Self, W> where Self: Sized {
529 Tee { reader: self, writer: out }
533 /// A trait for objects which are byte-oriented sinks.
535 /// The `write` method will attempt to write some data into the object,
536 /// returning how many bytes were successfully written.
538 /// The `flush` method is useful for adaptors and explicit buffers themselves
539 /// for ensuring that all buffered data has been pushed out to the "true sink".
541 /// * The `write()` method will attempt to write some data into the object,
542 /// returning how many bytes were successfully written.
544 /// * The `flush()` method is useful for adaptors and explicit buffers
545 /// themselves for ensuring that all buffered data has been pushed out to the
548 /// Writers are intended to be composable with one another. Many implementors
549 /// throughout `std::io` take and provide types which implement the `Write`
555 /// use std::io::prelude::*;
556 /// use std::fs::File;
558 /// # fn foo() -> std::io::Result<()> {
559 /// let mut buffer = try!(File::create("foo.txt"));
561 /// try!(buffer.write(b"some bytes"));
565 #[stable(feature = "rust1", since = "1.0.0")]
567 /// Write a buffer into this object, returning how many bytes were written.
569 /// This function will attempt to write the entire contents of `buf`, but
570 /// the entire write may not succeed, or the write may also generate an
571 /// error. A call to `write` represents *at most one* attempt to write to
572 /// any wrapped object.
574 /// Calls to `write` are not guaranteed to block waiting for data to be
575 /// written, and a write which would otherwise block can be indicated through
576 /// an `Err` variant.
578 /// If the return value is `Ok(n)` then it must be guaranteed that
579 /// `0 <= n <= buf.len()`. A return value of `0` typically means that the
580 /// underlying object is no longer able to accept bytes and will likely not
581 /// be able to in the future as well, or that the buffer provided is empty.
585 /// Each call to `write` may generate an I/O error indicating that the
586 /// operation could not be completed. If an error is returned then no bytes
587 /// in the buffer were written to this writer.
589 /// It is **not** considered an error if the entire buffer could not be
590 /// written to this writer.
591 #[stable(feature = "rust1", since = "1.0.0")]
592 fn write(&mut self, buf: &[u8]) -> Result<usize>;
594 /// Flush this output stream, ensuring that all intermediately buffered
595 /// contents reach their destination.
599 /// It is considered an error if not all bytes could be written due to
600 /// I/O errors or EOF being reached.
601 #[stable(feature = "rust1", since = "1.0.0")]
602 fn flush(&mut self) -> Result<()>;
604 /// Attempts to write an entire buffer into this write.
606 /// This method will continuously call `write` while there is more data to
607 /// write. This method will not return until the entire buffer has been
608 /// successfully written or an error occurs. The first error generated from
609 /// this method will be returned.
613 /// This function will return the first error that `write` returns.
614 #[stable(feature = "rust1", since = "1.0.0")]
615 fn write_all(&mut self, mut buf: &[u8]) -> Result<()> {
616 while !buf.is_empty() {
617 match self.write(buf) {
618 Ok(0) => return Err(Error::new(ErrorKind::WriteZero,
619 "failed to write whole buffer")),
620 Ok(n) => buf = &buf[n..],
621 Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
622 Err(e) => return Err(e),
628 /// Writes a formatted string into this writer, returning any error
631 /// This method is primarily used to interface with the `format_args!`
632 /// macro, but it is rare that this should explicitly be called. The
633 /// `write!` macro should be favored to invoke this method instead.
635 /// This function internally uses the `write_all` method on this trait and
636 /// hence will continuously write data so long as no errors are received.
637 /// This also means that partial writes are not indicated in this signature.
641 /// This function will return any I/O error reported while formatting.
642 #[stable(feature = "rust1", since = "1.0.0")]
643 fn write_fmt(&mut self, fmt: fmt::Arguments) -> Result<()> {
644 // Create a shim which translates a Write to a fmt::Write and saves
645 // off I/O errors. instead of discarding them
646 struct Adaptor<'a, T: ?Sized + 'a> {
651 impl<'a, T: Write + ?Sized> fmt::Write for Adaptor<'a, T> {
652 fn write_str(&mut self, s: &str) -> fmt::Result {
653 match self.inner.write_all(s.as_bytes()) {
663 let mut output = Adaptor { inner: self, error: Ok(()) };
664 match fmt::write(&mut output, fmt) {
666 Err(..) => output.error
670 /// Creates a "by reference" adaptor for this instance of `Write`.
672 /// The returned adaptor also implements `Write` and will simply borrow this
674 #[stable(feature = "rust1", since = "1.0.0")]
675 fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
677 /// Creates a new writer which will write all data to both this writer and
680 /// All data written to the returned writer will both be written to `self`
681 /// as well as `other`. Note that the error semantics of the current
682 /// implementation do not precisely track where errors happen. For example
683 /// an error on the second call to `write` will not report that the first
684 /// call to `write` succeeded.
685 #[unstable(feature = "io", reason = "the semantics of a partial read/write \
686 of where errors happen is currently \
687 unclear and may change")]
688 fn broadcast<W: Write>(self, other: W) -> Broadcast<Self, W>
691 Broadcast { first: self, second: other }
695 /// The `Seek` trait provides a cursor which can be moved within a stream of
698 /// The stream typically has a fixed size, allowing seeking relative to either
699 /// end or the current offset.
703 /// [`File`][file]s implement `Seek`:
705 /// [file]: ../std/fs/struct.File.html
709 /// use std::fs::File;
710 /// use std::io::Seek;
711 /// use std::io::SeekFrom;
713 /// # fn foo() -> io::Result<()> {
714 /// let mut f = try!(File::open("foo.txt"));
716 /// // move the cursor 42 bytes from the start of the file
717 /// f.seek(SeekFrom::Start(42)).unwrap();
721 #[stable(feature = "rust1", since = "1.0.0")]
723 /// Seek to an offset, in bytes, in a stream.
725 /// A seek beyond the end of a stream is allowed, but implementation
728 /// The behavior when seeking past the end of the stream is implementation
731 /// This method returns the new position within the stream if the seek
732 /// operation completed successfully.
736 /// Seeking to a negative offset is considered an error.
737 #[stable(feature = "rust1", since = "1.0.0")]
738 fn seek(&mut self, pos: SeekFrom) -> Result<u64>;
741 /// Enumeration of possible methods to seek within an I/O object.
742 #[derive(Copy, PartialEq, Eq, Clone, Debug)]
743 #[stable(feature = "rust1", since = "1.0.0")]
745 /// Set the offset to the provided number of bytes.
746 #[stable(feature = "rust1", since = "1.0.0")]
749 /// Set the offset to the size of this object plus the specified number of
752 /// It is possible to seek beyond the end of an object, but is an error to
753 /// seek before byte 0.
754 #[stable(feature = "rust1", since = "1.0.0")]
757 /// Set the offset to the current position plus the specified number of
760 /// It is possible to seek beyond the end of an object, but is an error to
761 /// seek before byte 0.
762 #[stable(feature = "rust1", since = "1.0.0")]
766 fn read_until<R: BufRead + ?Sized>(r: &mut R, delim: u8, buf: &mut Vec<u8>)
771 let available = match r.fill_buf() {
773 Err(ref e) if e.kind() == ErrorKind::Interrupted => continue,
774 Err(e) => return Err(e)
776 match available.position_elem(&delim) {
778 buf.push_all(&available[..i + 1]);
782 buf.push_all(available);
783 (false, available.len())
789 if done || used == 0 {
795 /// A `BufRead` is a type of `Read`er which has an internal buffer, allowing it
796 /// to perform extra ways of reading.
798 /// For example, reading line-by-line is inefficient without using a buffer, so
799 /// if you want to read by line, you'll need `BufRead`, which includes a
800 /// [`read_line()`][readline] method as well as a [`lines()`][lines] iterator.
802 /// [readline]: #method.read_line
803 /// [lines]: #method.lines
807 /// A locked standard input implements `BufRead`:
811 /// use std::io::BufRead;
813 /// let stdin = io::stdin();
814 /// for line in stdin.lock().lines() {
815 /// println!("{}", line.unwrap());
819 /// If you have something that implements `Read`, you can use the [`BufReader`
820 /// type][bufreader] to turn it into a `BufRead`.
822 /// For example, [`File`][file] implements `Read`, but not `BufRead`.
823 /// `BufReader` to the rescue!
825 /// [bufreader]: struct.BufReader.html
826 /// [file]: ../fs/struct.File.html
830 /// use std::fs::File;
831 /// use std::io::BufRead;
832 /// use std::io::BufReader;
834 /// # fn foo() -> io::Result<()> {
835 /// let f = try!(File::open("foo.txt"));
836 /// let f = BufReader::new(f);
838 /// for line in f.lines() {
839 /// println!("{}", line.unwrap());
846 #[stable(feature = "rust1", since = "1.0.0")]
847 pub trait BufRead: Read {
848 /// Fills the internal buffer of this object, returning the buffer contents.
850 /// This function is a lower-level call. It needs to be paired with the
851 /// [`consume`][consume] method to function properly. When calling this
852 /// method, none of the contents will be "read" in the sense that later
853 /// calling `read` may return the same contents. As such, `consume` must be
854 /// called with the number of bytes that are consumed from this buffer to
855 /// ensure that the bytes are never returned twice.
857 /// [consume]: #tymethod.consume
859 /// An empty buffer returned indicates that the stream has reached EOF.
863 /// This function will return an I/O error if the underlying reader was
864 /// read, but returned an error.
868 /// A locked standard input implements `BufRead`:
872 /// use std::io::prelude::*;
874 /// let stdin = io::stdin();
875 /// let mut stdin = stdin.lock();
877 /// // we can't have two `&mut` references to `stdin`, so use a block
878 /// // to end the borrow early.
880 /// let buffer = stdin.fill_buf().unwrap();
882 /// // work with buffer
883 /// println!("{:?}", buffer);
888 /// // ensure the bytes we worked with aren't returned again later
889 /// stdin.consume(length);
891 #[stable(feature = "rust1", since = "1.0.0")]
892 fn fill_buf(&mut self) -> Result<&[u8]>;
894 /// Tells this buffer that `amt` bytes have been consumed from the buffer,
895 /// so they should no longer be returned in calls to `read`.
897 /// This function is a lower-level call. It needs to be paired with the
898 /// [`fill_buf`][fillbuf] method to function properly. This function does
899 /// not perform any I/O, it simply informs this object that some amount of
900 /// its buffer, returned from `fill_buf`, has been consumed and should no
901 /// longer be returned. As such, this function may do odd things if
902 /// `fill_buf` isn't called before calling it.
904 /// [fillbuf]: #tymethod.fill_buff
906 /// The `amt` must be `<=` the number of bytes in the buffer returned by
911 /// Since `consume()` is meant to be used with [`fill_buf()`][fillbuf],
912 /// that method's example includes an example of `consume()`.
913 #[stable(feature = "rust1", since = "1.0.0")]
914 fn consume(&mut self, amt: usize);
916 /// Read all bytes into `buf` until the delimiter `byte` is reached.
918 /// This function will read bytes from the underlying stream until the
919 /// delimiter or EOF is found. Once found, all bytes up to, and including,
920 /// the delimiter (if found) will be appended to `buf`.
922 /// If this reader is currently at EOF then this function will not modify
923 /// `buf` and will return `Ok(n)` where `n` is the number of bytes which
928 /// This function will ignore all instances of `ErrorKind::Interrupted` and
929 /// will otherwise return any errors returned by `fill_buf`.
931 /// If an I/O error is encountered then all bytes read so far will be
932 /// present in `buf` and its length will have been adjusted appropriately.
936 /// A locked standard input implements `BufRead`. In this example, we'll
937 /// read from standard input until we see an `a` byte.
941 /// use std::io::prelude::*;
943 /// fn foo() -> io::Result<()> {
944 /// let stdin = io::stdin();
945 /// let mut stdin = stdin.lock();
946 /// let mut buffer = Vec::new();
948 /// try!(stdin.read_until(b'a', &mut buffer));
950 /// println!("{:?}", buffer);
954 #[stable(feature = "rust1", since = "1.0.0")]
955 fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize> {
956 read_until(self, byte, buf)
959 /// Read all bytes until a newline (the 0xA byte) is reached, and append
960 /// them to the provided buffer.
962 /// This function will read bytes from the underlying stream until the
963 /// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes
964 /// up to, and including, the delimiter (if found) will be appended to
967 /// If this reader is currently at EOF then this function will not modify
968 /// `buf` and will return `Ok(n)` where `n` is the number of bytes which
973 /// This function has the same error semantics as `read_until` and will also
974 /// return an error if the read bytes are not valid UTF-8. If an I/O error
975 /// is encountered then `buf` may contain some bytes already read in the
976 /// event that all data read so far was valid UTF-8.
980 /// A locked standard input implements `BufRead`. In this example, we'll
981 /// read all of the lines from standard input. If we were to do this in
982 /// an actual project, the [`lines()`][lines] method would be easier, of
985 /// [lines]: #method.lines
989 /// use std::io::prelude::*;
991 /// let stdin = io::stdin();
992 /// let mut stdin = stdin.lock();
993 /// let mut buffer = String::new();
995 /// while stdin.read_line(&mut buffer).unwrap() > 0 {
996 /// // work with buffer
997 /// println!("{:?}", buffer);
1002 #[stable(feature = "rust1", since = "1.0.0")]
1003 fn read_line(&mut self, buf: &mut String) -> Result<usize> {
1004 // Note that we are not calling the `.read_until` method here, but
1005 // rather our hardcoded implementation. For more details as to why, see
1006 // the comments in `read_to_end`.
1007 append_to_string(buf, |b| read_until(self, b'\n', b))
1010 /// Returns an iterator over the contents of this reader split on the byte
1013 /// The iterator returned from this function will return instances of
1014 /// `io::Result<Vec<u8>>`. Each vector returned will *not* have the
1015 /// delimiter byte at the end.
1017 /// This function will yield errors whenever `read_until` would have also
1018 /// yielded an error.
1022 /// A locked standard input implements `BufRead`. In this example, we'll
1023 /// read some input from standard input, splitting on commas.
1027 /// use std::io::prelude::*;
1029 /// let stdin = io::stdin();
1031 /// for content in stdin.lock().split(b',') {
1032 /// println!("{:?}", content.unwrap());
1035 #[stable(feature = "rust1", since = "1.0.0")]
1036 fn split(self, byte: u8) -> Split<Self> where Self: Sized {
1037 Split { buf: self, delim: byte }
1040 /// Returns an iterator over the lines of this reader.
1042 /// The iterator returned from this function will yield instances of
1043 /// `io::Result<String>`. Each string returned will *not* have a newline
1044 /// byte (the 0xA byte) at the end.
1048 /// A locked standard input implements `BufRead`:
1052 /// use std::io::prelude::*;
1054 /// let stdin = io::stdin();
1056 /// for line in stdin.lock().lines() {
1057 /// println!("{}", line.unwrap());
1060 #[stable(feature = "rust1", since = "1.0.0")]
1061 fn lines(self) -> Lines<Self> where Self: Sized {
1066 /// A `Write` adaptor which will write data to multiple locations.
1068 /// For more information, see `Write::broadcast`.
1069 #[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
1070 pub struct Broadcast<T, U> {
1075 #[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
1076 impl<T: Write, U: Write> Write for Broadcast<T, U> {
1077 fn write(&mut self, data: &[u8]) -> Result<usize> {
1078 let n = try!(self.first.write(data));
1079 // FIXME: what if the write fails? (we wrote something)
1080 try!(self.second.write_all(&data[..n]));
1084 fn flush(&mut self) -> Result<()> {
1085 self.first.flush().and(self.second.flush())
1089 /// Adaptor to chain together two instances of `Read`.
1091 /// For more information, see `Read::chain`.
1092 #[stable(feature = "rust1", since = "1.0.0")]
1093 pub struct Chain<T, U> {
1099 #[stable(feature = "rust1", since = "1.0.0")]
1100 impl<T: Read, U: Read> Read for Chain<T, U> {
1101 fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
1102 if !self.done_first {
1103 match try!(self.first.read(buf)) {
1104 0 => { self.done_first = true; }
1108 self.second.read(buf)
1112 /// Reader adaptor which limits the bytes read from an underlying reader.
1114 /// For more information, see `Read::take`.
1115 #[stable(feature = "rust1", since = "1.0.0")]
1116 pub struct Take<T> {
1121 #[stable(feature = "rust1", since = "1.0.0")]
1123 /// Returns the number of bytes that can be read before this instance will
1128 /// This instance may reach EOF after reading fewer bytes than indicated by
1129 /// this method if the underlying `Read` instance reaches EOF.
1130 #[stable(feature = "rust1", since = "1.0.0")]
1131 pub fn limit(&self) -> u64 { self.limit }
1134 #[stable(feature = "rust1", since = "1.0.0")]
1135 impl<T: Read> Read for Take<T> {
1136 fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
1137 // Don't call into inner reader at all at EOF because it may still block
1138 if self.limit == 0 {
1142 let max = cmp::min(buf.len() as u64, self.limit) as usize;
1143 let n = try!(self.inner.read(&mut buf[..max]));
1144 self.limit -= n as u64;
1149 #[stable(feature = "rust1", since = "1.0.0")]
1150 impl<T: BufRead> BufRead for Take<T> {
1151 fn fill_buf(&mut self) -> Result<&[u8]> {
1152 let buf = try!(self.inner.fill_buf());
1153 let cap = cmp::min(buf.len() as u64, self.limit) as usize;
1157 fn consume(&mut self, amt: usize) {
1158 // Don't let callers reset the limit by passing an overlarge value
1159 let amt = cmp::min(amt as u64, self.limit) as usize;
1160 self.limit -= amt as u64;
1161 self.inner.consume(amt);
1165 /// An adaptor which will emit all read data to a specified writer as well.
1167 /// For more information see `Read::tee`
1168 #[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
1169 pub struct Tee<R, W> {
1174 #[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
1175 impl<R: Read, W: Write> Read for Tee<R, W> {
1176 fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
1177 let n = try!(self.reader.read(buf));
1178 // FIXME: what if the write fails? (we read something)
1179 try!(self.writer.write_all(&buf[..n]));
1184 /// A bridge from implementations of `Read` to an `Iterator` of `u8`.
1186 /// See `Read::bytes` for more information.
1187 #[stable(feature = "rust1", since = "1.0.0")]
1188 pub struct Bytes<R> {
1192 #[stable(feature = "rust1", since = "1.0.0")]
1193 impl<R: Read> Iterator for Bytes<R> {
1194 type Item = Result<u8>;
1196 fn next(&mut self) -> Option<Result<u8>> {
1198 match self.inner.read(&mut buf) {
1200 Ok(..) => Some(Ok(buf[0])),
1201 Err(e) => Some(Err(e)),
1206 /// A bridge from implementations of `Read` to an `Iterator` of `char`.
1208 /// See `Read::chars` for more information.
1209 #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
1210 pub struct Chars<R> {
1214 /// An enumeration of possible errors that can be generated from the `Chars`
1217 #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
1218 pub enum CharsError {
1219 /// Variant representing that the underlying stream was read successfully
1220 /// but it did not contain valid utf8 data.
1223 /// Variant representing that an I/O error occurred.
1227 #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
1228 impl<R: Read> Iterator for Chars<R> {
1229 type Item = result::Result<char, CharsError>;
1231 fn next(&mut self) -> Option<result::Result<char, CharsError>> {
1233 let first_byte = match self.inner.read(&mut buf) {
1234 Ok(0) => return None,
1236 Err(e) => return Some(Err(CharsError::Other(e))),
1238 let width = core_str::utf8_char_width(first_byte);
1239 if width == 1 { return Some(Ok(first_byte as char)) }
1240 if width == 0 { return Some(Err(CharsError::NotUtf8)) }
1241 let mut buf = [first_byte, 0, 0, 0];
1244 while start < width {
1245 match self.inner.read(&mut buf[start..width]) {
1246 Ok(0) => return Some(Err(CharsError::NotUtf8)),
1247 Ok(n) => start += n,
1248 Err(e) => return Some(Err(CharsError::Other(e))),
1252 Some(match str::from_utf8(&buf[..width]).ok() {
1253 Some(s) => Ok(s.char_at(0)),
1254 None => Err(CharsError::NotUtf8),
1259 #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
1260 impl std_error::Error for CharsError {
1261 fn description(&self) -> &str {
1263 CharsError::NotUtf8 => "invalid utf8 encoding",
1264 CharsError::Other(ref e) => std_error::Error::description(e),
1267 fn cause(&self) -> Option<&std_error::Error> {
1269 CharsError::NotUtf8 => None,
1270 CharsError::Other(ref e) => e.cause(),
1275 #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
1276 impl fmt::Display for CharsError {
1277 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1279 CharsError::NotUtf8 => {
1280 "byte stream did not contain valid utf8".fmt(f)
1282 CharsError::Other(ref e) => e.fmt(f),
1287 /// An iterator over the contents of an instance of `BufRead` split on a
1288 /// particular byte.
1290 /// See `BufRead::split` for more information.
1291 #[stable(feature = "rust1", since = "1.0.0")]
1292 pub struct Split<B> {
1297 #[stable(feature = "rust1", since = "1.0.0")]
1298 impl<B: BufRead> Iterator for Split<B> {
1299 type Item = Result<Vec<u8>>;
1301 fn next(&mut self) -> Option<Result<Vec<u8>>> {
1302 let mut buf = Vec::new();
1303 match self.buf.read_until(self.delim, &mut buf) {
1306 if buf[buf.len() - 1] == self.delim {
1311 Err(e) => Some(Err(e))
1316 /// An iterator over the lines of an instance of `BufRead` split on a newline
1319 /// See `BufRead::lines` for more information.
1320 #[stable(feature = "rust1", since = "1.0.0")]
1321 pub struct Lines<B> {
1325 #[stable(feature = "rust1", since = "1.0.0")]
1326 impl<B: BufRead> Iterator for Lines<B> {
1327 type Item = Result<String>;
1329 fn next(&mut self) -> Option<Result<String>> {
1330 let mut buf = String::new();
1331 match self.buf.read_line(&mut buf) {
1334 if buf.ends_with("\n") {
1339 Err(e) => Some(Err(e))
1353 let mut buf = Cursor::new(&b"12"[..]);
1354 let mut v = Vec::new();
1355 assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 2);
1356 assert_eq!(v, b"12");
1358 let mut buf = Cursor::new(&b"1233"[..]);
1359 let mut v = Vec::new();
1360 assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 3);
1361 assert_eq!(v, b"123");
1363 assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 1);
1364 assert_eq!(v, b"3");
1366 assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 0);
1372 let buf = Cursor::new(&b"12"[..]);
1373 let mut s = buf.split(b'3');
1374 assert_eq!(s.next().unwrap().unwrap(), vec![b'1', b'2']);
1375 assert!(s.next().is_none());
1377 let buf = Cursor::new(&b"1233"[..]);
1378 let mut s = buf.split(b'3');
1379 assert_eq!(s.next().unwrap().unwrap(), vec![b'1', b'2']);
1380 assert_eq!(s.next().unwrap().unwrap(), vec![]);
1381 assert!(s.next().is_none());
1386 let mut buf = Cursor::new(&b"12"[..]);
1387 let mut v = String::new();
1388 assert_eq!(buf.read_line(&mut v).unwrap(), 2);
1389 assert_eq!(v, "12");
1391 let mut buf = Cursor::new(&b"12\n\n"[..]);
1392 let mut v = String::new();
1393 assert_eq!(buf.read_line(&mut v).unwrap(), 3);
1394 assert_eq!(v, "12\n");
1396 assert_eq!(buf.read_line(&mut v).unwrap(), 1);
1397 assert_eq!(v, "\n");
1399 assert_eq!(buf.read_line(&mut v).unwrap(), 0);
1405 let buf = Cursor::new(&b"12"[..]);
1406 let mut s = buf.lines();
1407 assert_eq!(s.next().unwrap().unwrap(), "12".to_string());
1408 assert!(s.next().is_none());
1410 let buf = Cursor::new(&b"12\n\n"[..]);
1411 let mut s = buf.lines();
1412 assert_eq!(s.next().unwrap().unwrap(), "12".to_string());
1413 assert_eq!(s.next().unwrap().unwrap(), "".to_string());
1414 assert!(s.next().is_none());
1419 let mut c = Cursor::new(&b""[..]);
1420 let mut v = Vec::new();
1421 assert_eq!(c.read_to_end(&mut v).unwrap(), 0);
1424 let mut c = Cursor::new(&b"1"[..]);
1425 let mut v = Vec::new();
1426 assert_eq!(c.read_to_end(&mut v).unwrap(), 1);
1427 assert_eq!(v, b"1");
1429 let cap = 1024 * 1024;
1430 let data = (0..cap).map(|i| (i / 3) as u8).collect::<Vec<_>>();
1431 let mut v = Vec::new();
1432 let (a, b) = data.split_at(data.len() / 2);
1433 assert_eq!(Cursor::new(a).read_to_end(&mut v).unwrap(), a.len());
1434 assert_eq!(Cursor::new(b).read_to_end(&mut v).unwrap(), b.len());
1435 assert_eq!(v, data);
1439 fn read_to_string() {
1440 let mut c = Cursor::new(&b""[..]);
1441 let mut v = String::new();
1442 assert_eq!(c.read_to_string(&mut v).unwrap(), 0);
1445 let mut c = Cursor::new(&b"1"[..]);
1446 let mut v = String::new();
1447 assert_eq!(c.read_to_string(&mut v).unwrap(), 1);
1450 let mut c = Cursor::new(&b"\xff"[..]);
1451 let mut v = String::new();
1452 assert!(c.read_to_string(&mut v).is_err());
1460 fn read(&mut self, _: &mut [u8]) -> io::Result<usize> {
1461 Err(io::Error::new(io::ErrorKind::Other, ""))
1465 let mut buf = [0; 1];
1466 assert_eq!(0, R.take(0).read(&mut buf).unwrap());