Trait std::io::Read
[−]
[src]
pub trait Read { fn read(&mut self, buf: &mut [u8]) -> Result<usize>; fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> { ... } fn read_to_string(&mut self, buf: &mut String) -> Result<usize> { ... } fn by_ref(&mut self) -> &mut Self where Self: Sized { ... } fn bytes(self) -> Bytes<Self> where Self: Sized { ... } fn chars(self) -> Chars<Self> where Self: Sized { ... } fn chain<R: Read>(self, next: R) -> Chain<Self, R> where Self: Sized { ... } fn take(self, limit: u64) -> Take<Self> where Self: Sized { ... } fn tee<W: Write>(self, out: W) -> Tee<Self, W> where Self: Sized { ... } }
The Read
`Read` trait allows for reading bytes from a source.
Implementors of the Read
`Read` trait are sometimes called 'readers'.
Readers are defined by one required method, read()
`read(). Each call to
readwill attempt to pull bytes from this source into a provided buffer. A number of other methods are implemented in terms of
read()`, giving
implementors a number of ways to read bytes while only needing to implement
a single method.
Readers are intended to be composable with one another. Many implementors
throughout std::io
`std::iotake and provide types which implement the
Read`
trait.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); let mut buffer = [0; 10]; // read up to 10 bytes try!(f.read(&mut buffer)); let mut buffer = vec![0; 10]; // read the whole file try!(f.read_to_end(&mut buffer)); // read into a String, so that you don't need to do the conversion. let mut buffer = String::new(); try!(f.read_to_string(&mut buffer)); // and more! See the other methods for more details.
Required Methods
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Pull some bytes from this source into the specified buffer, returning how many bytes were read.
This function does not provide any guarantees about whether it blocks
waiting for data, but if an object needs to block for a read but cannot
it will typically signal this via an Err
`Err` return value.
If the return value of this method is Ok(n)
`Ok(n), then it must be guaranteed that
0 <= n <= buf.len(). A nonzero
nvalue indicates that the buffer
bufhas been filled in with
nbytes of data from this source. If
nis
` is 0
`0`, then it can indicate one of two scenarios:
- This reader has reached its "end of file" and will likely no longer be able to produce bytes. Note that this does not mean that the reader will always no longer be able to produce bytes.
- The buffer specified was 0 bytes in length.
No guarantees are provided about the contents of buf
`bufwhen this function is called, implementations cannot rely on any property of the contents of
bufbeing true. It is recommended that implementations only write data to
buf` instead of reading its contents.
Errors
If this function encounters any form of I/O or other error, an error variant will be returned. If an error is returned then it must be guaranteed that no bytes were read.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); let mut buffer = [0; 10]; // read 10 bytes try!(f.read(&mut buffer[..]));
Provided Methods
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>
Read all bytes until EOF in this source, placing them into buf
`buf`.
All bytes read from this source will be appended to the specified buffer
buf
`buf. This function will continuously call
readto append more data to
bufuntil
` until read
`readreturns either
Ok(0)or an error of non-
ErrorKind::Interrupted` kind.
If successful, this function will return the total number of bytes read.
Errors
If this function encounters an error of the kind
ErrorKind::Interrupted
then the error is ignored and the operation
will continue.
If any other read error is encountered then this function immediately
returns. Any bytes which have already been read will be appended to
buf
`buf`.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); let mut buffer = Vec::new(); // read the whole file try!(f.read_to_end(&mut buffer));
fn read_to_string(&mut self, buf: &mut String) -> Result<usize>
Read all bytes until EOF in this source, placing them into buf
`buf`.
If successful, this function returns the number of bytes which were read
and appended to buf
`buf`.
Errors
If the data in this stream is not valid UTF-8 then an error is
returned and buf
`buf` is unchanged.
See read_to_end()
for other error semantics.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); let mut buffer = String::new(); try!(f.read_to_string(&mut buffer));
fn by_ref(&mut self) -> &mut Self where Self: Sized
Creates a "by reference" adaptor for this instance of Read
`Read`.
The returned adaptor also implements Read
`Read` and will simply borrow this
current reader.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::Read; use std::fs::File; let mut f = try!(File::open("foo.txt")); let mut buffer = Vec::new(); let mut other_buffer = Vec::new(); { let reference = f.by_ref(); // read at most 5 bytes try!(reference.take(5).read_to_end(&mut buffer)); } // drop our &mut reference so we can use f again // original file still usable, read the rest try!(f.read_to_end(&mut other_buffer));
fn bytes(self) -> Bytes<Self> where Self: Sized
Transforms this Read
`Readinstance to an
Iterator` over its bytes.
The returned type implements Iterator
`Iteratorwhere the
Itemis
` is Result<u8, R::Err>
. The yielded item is Ok
`Okif a byte was successfully read and
Errotherwise for I/O errors. EOF is mapped to returning
None` from
this iterator.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); for byte in f.bytes() { println!("{}", byte.unwrap()); }
fn chars(self) -> Chars<Self> where Self: Sized
: the semantics of a partial read/write of where errors happen is currently unclear and may change
Transforms this Read
`Readinstance to an
Iteratorover
` over char
`char`s.
This adaptor will attempt to interpret this reader as a UTF-8 encoded
sequence of characters. The returned iterator will return None
`Noneonce EOF is reached for this reader. Otherwise each element yielded will be a
Resultwhere
` where E
`E` may contain information about what I/O error
occurred or where decoding failed.
Currently this adaptor will discard intermediate data read, and should be avoided if this is not desired.
Examples
File
`File`s implement Read
`Read`:
#![feature(io)] use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); for c in f.chars() { println!("{}", c.unwrap()); }
fn chain<R: Read>(self, next: R) -> Chain<Self, R> where Self: Sized
Creates an adaptor which will chain this stream with another.
The returned Read
`Readinstance will first read all bytes from this object until EOF is encountered. Afterwards the output is equivalent to the output of
next`.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::prelude::*; use std::fs::File; let mut f1 = try!(File::open("foo.txt")); let mut f2 = try!(File::open("bar.txt")); let mut handle = f1.chain(f2); let mut buffer = String::new(); // read the value into a String. We could use any Read method here, // this is just one example. try!(handle.read_to_string(&mut buffer));
fn take(self, limit: u64) -> Take<Self> where Self: Sized
Creates an adaptor which will read at most limit
`limit` bytes from it.
This function returns a new instance of Read
`Readwhich will read at most
limitbytes, after which it will always return EOF (
Ok(0)). Any read errors will not count towards the number of bytes read and future calls to
read` may succeed.
Examples
File
`File`s implement Read
`Read`:
use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); let mut buffer = [0; 5]; // read at most five bytes let mut handle = f.take(5); try!(handle.read(&mut buffer));
fn tee<W: Write>(self, out: W) -> Tee<Self, W> where Self: Sized
: the semantics of a partial read/write of where errors happen is currently unclear and may change
Creates a reader adaptor which will write all read data into the given output stream.
Whenever the returned Read
`Readinstance is read it will write the read data to
out. The current semantics of this implementation imply that a
write` error will not report how much data was initially read.
Examples
File
`File`s implement Read
`Read`:
#![feature(io)] use std::io; use std::io::prelude::*; use std::fs::File; let mut f = try!(File::open("foo.txt")); let mut buffer1 = Vec::with_capacity(10); let mut buffer2 = Vec::with_capacity(10); // write the output to buffer1 as we read let mut handle = f.tee(&mut buffer1); try!(handle.read(&mut buffer2));
Implementors
impl Read for File
impl<'a> Read for &'a File
impl<R: Read> Read for BufReader<R>
impl<S: Read + Write> Read for BufStream<S>
impl<'a> Read for Cursor<&'a [u8]>
impl<'a> Read for Cursor<&'a mut [u8]>
impl Read for Cursor<Vec<u8>>
impl<'a, R: Read + ?Sized> Read for &'a mut R
impl<R: Read + ?Sized> Read for Box<R>
impl<'a> Read for &'a [u8]
impl Read for Empty
impl Read for Repeat
impl Read for Stdin
impl<'a> Read for StdinLock<'a>
impl<T: Read, U: Read> Read for Chain<T, U>
impl<T: Read> Read for Take<T>
impl<R: Read, W: Write> Read for Tee<R, W>
impl Read for TcpStream
impl<'a> Read for &'a TcpStream
impl Read for ChildStdout
impl Read for ChildStderr