Trait genio::Read [−] [src]

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

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

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

Required Methods

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:

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

Provided Methods

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.

Hints whether there are at least at_least bytes available.

This function should return true if it can't determine exact amount. That is also default.

Errors

It is an error to return false even if there are more bytes available.

Chains another reader after self. When self ends (returns Ok(0)), the other reader will provide bytes to read.

Reads all bytes into any type that can be extended by a reader. This is more generic than the case of std::io and might enable some optimizations.

Of course, std::Vec impls ExtendFromReader.

Creates a "by reference" adaptor for this instance of Read.

The returned adaptor also implements Read and will simply borrow this current reader.

Implementors