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 { ... }
}

A trait for objects which are byte-oriented sources.

Readers are defined by one method, read`read. Each call to`. Each call to read`read` will attempt to pull bytes from this source into a provided buffer.

Readers are intended to be composable with one another. Many objects throughout the I/O and related libraries take and provide types which implement the Read`Read` trait.

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`, then it must be guaranteed that 0 <= n <= buf.len()`0 <= n <= buf.len(). A nonzero`. A nonzero n`nvalue indicates that the buffer` value indicates that the buffer buf`bufhas been filled in with` has been filled in with n`nbytes of data from this source. If` bytes of data from this source. If n`nis` is 0`0`, then it can indicate one of two scenarios:

  1. 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.
  2. 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` when this function is called, implementations cannot rely on any property of the contents of buf`bufbeing true. It is recommended that implementations only write data to` being true. It is recommended that implementations only write data to buf`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.

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`. This function will continuously call read`readto append more data to` to append more data to buf`bufuntil` until read`readreturns either` returns either Ok(0)`Ok(0)or an error of non-` or an error of non-ErrorKind::Interrupted`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`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`.

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`read_to_end` for other error semantics.

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.

fn bytes(self) -> Bytes<Self> where Self: Sized

Transforms this Read`Readinstance to an` instance to an Iterator`Iterator` over its bytes.

The returned type implements Iterator`Iteratorwhere the` where the Item`Itemis` is Result<u8, R::Err>`Result. The yielded item is`. The yielded item is Ok`Okif a byte was successfully read and` if a byte was successfully read and Err`Errotherwise for I/O errors. EOF is mapped to returning` otherwise for I/O errors. EOF is mapped to returning None`None` from this iterator.

fn chars(self) -> Chars<Self> where Self: Sized

Unstable

: the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read`Readinstance to an` instance to an Iterator`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` once EOF is reached for this reader. Otherwise each element yielded will be a Result<char, E>`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.

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` instance will first read all bytes from this object until EOF is encountered. Afterwards the output is equivalent to the output of next`next`.

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` which will read at most limit`limitbytes, after which it will always return EOF (` bytes, after which it will always return EOF (Ok(0)`Ok(0)). Any read errors will not count towards the number of bytes read and future calls to`). Any read errors will not count towards the number of bytes read and future calls to read`read` may succeed.

fn tee<W: Write>(self, out: W) -> Tee<Self, W> where Self: Sized

Unstable

: 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` instance is read it will write the read data to out`out. The current semantics of this implementation imply that a`. The current semantics of this implementation imply that a write`write` error will not report how much data was initially read.

Implementors