pub trait Read {
type ReadError;
// Required method
fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::ReadError>;
// Provided methods
fn read_exact(
&mut self,
buf: &mut [u8],
) -> Result<(), ReadExactError<Self::ReadError>> { ... }
fn available_bytes(&self, _at_least: usize) -> bool { ... }
fn chain<R>(self, other: R) -> Chain<Self, R>
where R: Read,
Self: Sized { ... }
fn read_to_end<T>(
&mut self,
container: &mut T,
) -> Result<usize, ExtendError<Self::ReadError, <T as ExtendFromReaderSlow>::ExtendError>>
where T: ExtendFromReader,
Self: ReadOverwrite { ... }
fn by_ref(&mut self) -> &mut Self
where Self: Sized { ... }
}Expand description
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.
Required Associated Types§
Required Methods§
Sourcefn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::ReadError>
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.
Provided Methods§
Sourcefn read_exact(
&mut self,
buf: &mut [u8],
) -> Result<(), ReadExactError<Self::ReadError>>
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.
Sourcefn available_bytes(&self, _at_least: usize) -> bool
fn available_bytes(&self, _at_least: usize) -> bool
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.
Sourcefn chain<R>(self, other: R) -> Chain<Self, R>
fn chain<R>(self, other: R) -> Chain<Self, R>
Chains another reader after self. When self ends (returns Ok(0)), the other reader will
provide bytes to read.
Sourcefn read_to_end<T>(
&mut self,
container: &mut T,
) -> Result<usize, ExtendError<Self::ReadError, <T as ExtendFromReaderSlow>::ExtendError>>where
T: ExtendFromReader,
Self: ReadOverwrite,
fn read_to_end<T>(
&mut self,
container: &mut T,
) -> Result<usize, ExtendError<Self::ReadError, <T as ExtendFromReaderSlow>::ExtendError>>where
T: ExtendFromReader,
Self: ReadOverwrite,
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.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.