pub trait ZByteReaderTrait {
// Required methods
fn read_byte_no_error(&mut self) -> u8;
fn read_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>;
fn read_const_bytes<const N: usize>(
&mut self,
buf: &mut [u8; N],
) -> Result<(), ZByteIoError>;
fn read_const_bytes_no_error<const N: usize>(&mut self, buf: &mut [u8; N]);
fn read_bytes(&mut self, buf: &mut [u8]) -> Result<usize, ZByteIoError>;
fn peek_bytes(&mut self, buf: &mut [u8]) -> Result<usize, ZByteIoError>;
fn peek_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>;
fn z_seek(&mut self, from: ZSeekFrom) -> Result<u64, ZByteIoError>;
fn is_eof(&mut self) -> Result<bool, ZByteIoError>;
fn z_position(&mut self) -> Result<u64, ZByteIoError>;
fn read_remaining(
&mut self,
sink: &mut Vec<u8>,
) -> Result<usize, ZByteIoError>;
}
Expand description
The de-facto Input trait implemented for readers.
This provides the basic functions needed to quick and sometimes heap free I/O for the zune image decoders with easy support for extending it to multiple implementations.
§Considerations
If you have an in memory buffer, prefer ZCursor
over Cursor
.
We implement this trait for two types, ZCursor
, and any thing that implements BufRead
+Seek
, Cursor
falls in the latter
and since Rust doesn’t have specialization for traits, we can only implement it once. This means functions like
read_byte_no_error
are slower than they should be for Cursor
.
Required Methods§
Sourcefn read_byte_no_error(&mut self) -> u8
fn read_byte_no_error(&mut self) -> u8
Read a single byte from the decoder and return
0
if we can’t read the byte, e.g because of EOF
The implementation should try to be as fast as possible as this is called from some hot loops where it may become the bottleneck
Sourcefn read_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>
fn read_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>
Sourcefn read_const_bytes<const N: usize>(
&mut self,
buf: &mut [u8; N],
) -> Result<(), ZByteIoError>
fn read_const_bytes<const N: usize>( &mut self, buf: &mut [u8; N], ) -> Result<(), ZByteIoError>
Read exact bytes required to fill buf
or return an error if that isn’t possible
This is the same as read_exact_bytes
but implemented as a separate
method to allow some implementations to optimize it to cost fewer instructions
§Arguments
buf
: Buffer to fill with bytes from the underlying reader
§Errors
In case of an error, the implementation should not increment the internal position
Sourcefn read_const_bytes_no_error<const N: usize>(&mut self, buf: &mut [u8; N])
fn read_const_bytes_no_error<const N: usize>(&mut self, buf: &mut [u8; N])
Read exact bytes required to fill buf
or ignore buf entirely if you can’t fill it
due to an error like the inability to fill the buffer completely
§Arguments
buf
: Buffer to fill with bytes from the underlying reader
§Errors
In case of an error, the implementation should not increment the internal position
Sourcefn read_bytes(&mut self, buf: &mut [u8]) -> Result<usize, ZByteIoError>
fn read_bytes(&mut self, buf: &mut [u8]) -> Result<usize, ZByteIoError>
Read bytes into buf
returning how many bytes you have read or an error if one occurred
This doesn’t guarantee that buf will be filled with bytes for such a guarantee see
read_exact_bytes
§Arguments
buf
: The buffer to fill with bytes
§Returns
Ok(usize)
- Actual bytes read into the bufferErr()
- The error encountered when reading bytes for which we couldn’t recover
Sourcefn peek_bytes(&mut self, buf: &mut [u8]) -> Result<usize, ZByteIoError>
fn peek_bytes(&mut self, buf: &mut [u8]) -> Result<usize, ZByteIoError>
Reads data into provided buffer but does not advance read position.
fn peek_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>
Sourcefn z_seek(&mut self, from: ZSeekFrom) -> Result<u64, ZByteIoError>
fn z_seek(&mut self, from: ZSeekFrom) -> Result<u64, ZByteIoError>
Sourcefn is_eof(&mut self) -> Result<bool, ZByteIoError>
fn is_eof(&mut self) -> Result<bool, ZByteIoError>
Report whether we are at the end of a stream.
§Warning
This may cause an additional syscall e.g when we are reading from a file, we must query the file multiple times to check if we really are at the end of the file and the user didn’t sneakily add more contents to it hence use it with care
§Returns
Ok(bool)
- The answer to whether or not we are at end of fileErr()
- The error that occurred when we queried the underlying reader if we were at EOF
Sourcefn z_position(&mut self) -> Result<u64, ZByteIoError>
fn z_position(&mut self) -> Result<u64, ZByteIoError>
Return the current position of the inner cursor.
This can be used to check the advancement of the cursor
Sourcefn read_remaining(&mut self, sink: &mut Vec<u8>) -> Result<usize, ZByteIoError>
fn read_remaining(&mut self, sink: &mut Vec<u8>) -> Result<usize, ZByteIoError>
Read all bytes remaining in this input to sink
until we hit eof
§Returns
Ok(usize)
The actual number of bytes added to the sinkErr()
An error that occurred when reading bytes
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.