[−][src]Trait genio::Read

pub trait Read {
    type ReadError;
    fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::ReadError>;

    fn read_exact(
        &mut self, 
        buf: &mut [u8]
    ) -> Result<(), ReadExactError<Self::ReadError>> { ... }
    fn available_bytes(&self, _at_least: usize) -> bool { ... }
    fn chain<R: Read>(self, other: R) -> Chain<Self, R>
    where
        Self: Sized,
    { ... }
    fn read_to_end<T: ExtendFromReader>(
        &mut self, 
        container: &mut T
    ) -> Result<usize, ExtendError<Self::ReadError, T::ExtendError>>
    where
        Self: ReadOverwrite,
    { ... }
    fn by_ref(&mut self) -> &mut Self
    where
        Self: Sized,
    { ... }
}

The Read trait allows for reading bytes from a source.

Implementors of the Read trait are sometimes called 'readers'.

Readers are defined by one required method, read() and a required type ReadError. Each call to read will 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 genio take and provide types which implement the Read trait.

Please note that each call to read may involve a system call, and therefore, using something that implements BufRead, such as BufReader, will be more efficient.

Associated Types

`type ReadError`

Value of this type is returned when read() fails.

It's highly recommended to use Void from void crate if read() can never fail.

Loading content...

Required methods

`fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::ReadError>`

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 return value.

If the return value of this method is Ok(n), then it must be guaranteed that 0 <= n <= buf.len(). A nonzero n value indicates that the buffer buf has been filled in with n bytes of data from this source. If n is 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 when this function is called, implementations cannot rely on any property of the contents of buf being 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.

Loading content...

Provided methods

`fn read_exact( &mut self, buf: &mut [u8] ) -> Result<(), ReadExactError<Self::ReadError>>`

Read the exact number of bytes required to fill buf.

This function reads as many bytes as necessary to completely fill the specified buffer buf.

No guarantees are provided about the contents of buf when this function is called, implementations cannot rely on any property of the contents of buf being true. It is recommended that implementations only write data to buf instead of reading its contents.