Trait ZByteReaderTrait

pub trait ZByteReaderTrait

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

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

fn read_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>

Read exact bytes required to fill buf or return an error if that isn't possible

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

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 buffer
  • Err() - The error encountered when reading bytes for which we couldn't recover
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>
fn z_seek(&mut self, from: ZSeekFrom) -> Result<u64, ZByteIoError>

Seek into a new position from the buffer

This is similar to the seek function in the Seek trait but implemented to work for no-std environments

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 file
  • Err() - The error that occurred when we queried the underlying reader if we were at EOF
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

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 sink
  • Err() An error that occurred when reading bytes

Implementors