pub trait Read<'data> {
// Required methods
fn read_next(&mut self) -> Result<u8>;
fn read_slice(&mut self, n: usize) -> Result<Cow<'data, [u8]>>;
fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>;
}
Expand description
The Read<'data>
trait allows for reading bytes with a lifetime of 'data
from some source.
Implementors of the Read<'data>
trait are called “zero-copy readers”.
Note that not every source will enable zero-copy reads. This is evident by
read_slice()
returning a Cow
(such that it might return a Vec
if
the bytes requested cannot be borrowed).
Required Methods§
sourcefn read_next(&mut self) -> Result<u8>
fn read_next(&mut self) -> Result<u8>
Reads the next byte from the source.
Errors
If this function encounters an error of the kind
ErrorKind::Interrupted
then the error is ignored and the operation
will continue.
An ErrorKind::UnexpectedEof
error is returned if this reader has
reached end-of-file before the call to this method.
If any other read error is encountered then this function immediately returns.
If this function returns an error, it is unspecified how many bytes got read.
sourcefn read_slice(&mut self, n: usize) -> Result<Cow<'data, [u8]>>
fn read_slice(&mut self, n: usize) -> Result<Cow<'data, [u8]>>
Reads n
bytes from this reader, borrowing bytes if possible.
As this trait is safe to implement, callers cannot rely on the number of
returned bytes being equal to n
for safety. Extra care needs to be
taken when unsafe
functions are used to access the read bytes. Callers
have to ensure that no unchecked out-of-bounds accesses are possible
even if the number of returned bytes are greater or less than n
.
Errors
If this function encounters an error of the kind
ErrorKind::Interrupted
then the error is ignored and the operation
will continue.
An ErrorKind::UnexpectedEof
error is returned if this reader has
reached end-of-file before the call to this method.
If any other read error is encountered then this function immediately returns.
If this function returns an error, it is unspecified how many bytes got read.
sourcefn read_array<const N: usize>(&mut self) -> Result<[u8; N]>
fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>
Reads exactly N
bytes from this reader.
Note that because this method returns an array it will always copy the bytes from the source regardless if zero-copy reads are possible.
Errors
If this function encounters an error of the kind
ErrorKind::Interrupted
then the error is ignored and the operation
will continue.
An ErrorKind::UnexpectedEof
error is returned if this reader has
reached end-of-file before the call to this method.
If any other read error is encountered then this function immediately returns.
If this function returns an error, it is unspecified how many bytes got read.