Struct zune_core::bytestream::ZByteReader

pub struct ZByteReader<T: ZReaderTrait> { /* private fields */ }

An encapsulation of a byte stream reader

This provides an interface similar to std::io::Cursor but it provides fine grained options for reading different integer data types from the underlying buffer.

There are two variants mainly error and non error variants, the error variants are useful for cases where you need bytes from the underlying stream, and cannot do with zero result. the non error variants are useful when you may have proved data already exists eg by using has method or you are okay with returning zero if the underlying buffer has been completely read.

Implementations

impl<T: ZReaderTrait> ZByteReader<T>

pub const fn new(buf: T) -> ZByteReader<T>

Create a new instance of the byte stream

Bytes will be read from the start of buf.

buf is expected to live as long as this and all references to it live

Returns

A byte reader which will pull bits from bye

pub fn consume(self) -> T

Destroy this reader returning the underlying source of the bytes from which we were decoding

pub fn skip(&mut self, num: usize)

Skip num bytes ahead of the stream.

This bumps up the internal cursor wit a wrapping addition The bytes between current position and num will be skipped

Arguments

num: How many bytes to skip

Note

This does not consider length of the buffer, so skipping more bytes than possible and then reading bytes will return an error if using error variants or zero if using non-error variants

Example

use zune_core::bytestream::ZByteReader;
let zero_to_hundred:Vec<u8> = (0..100).collect();
let mut stream = ZByteReader::new(&zero_to_hundred);
// skip 37 bytes
stream.skip(37);

assert_eq!(stream.get_u8(),37);

See rewind for moving the internal cursor back

pub fn rewind(&mut self, num: usize)

Undo a buffer read by moving the position pointer num bytes behind.

This operation will saturate at zero

pub fn has(&self, num: usize) -> bool

Return whether the underlying buffer has num bytes available for reading

Example

use zune_core::bytestream::ZByteReader;
let data = [0_u8;120];
let reader = ZByteReader::new(data.as_slice());
assert!(reader.has(3));
assert!(!reader.has(121));

pub fn get_bytes_left(&self) -> usize

Get number of bytes available in the stream

pub fn len(&self) -> usize

Get length of the underlying buffer.

To get the number of bytes left in the buffer, use remaining method

pub fn is_empty(&self) -> bool

Return true if the underlying buffer stream is empty

pub const fn get_position(&self) -> usize

Get current position of the buffer.

pub fn eof(&self) -> bool

Return true whether or not we read to the end of the buffer and have no more bytes left.

pub fn remaining(&self) -> usize

Get number of bytes unread inside this stream.

To get the length of the underlying stream, use len method

pub fn get(&mut self, num: usize) -> Result<&[u8], &'static str>

Get a part of the bytestream as a reference.

This increments the position to point past the bytestream if position+num is in bounds

pub fn peek_at( &self, position: usize, num_bytes: usize ) -> Result<&[u8], &'static str>

Look ahead position bytes and return a reference to num_bytes from that position, or an error if the peek would be out of bounds.

This doesn’t increment the position, bytes would have to be discarded at a later point.

pub fn get_fixed_bytes_or_err<const N: usize>( &mut self ) -> Result<[u8; N], &'static str>

Get a fixed amount of bytes or return an error if we cant satisfy the read

This should be combined with has since if there are no more bytes you get an error.

But it’s useful for cases where you expect bytes but they are not present

For the zero variant see, get_fixed_bytes_or_zero

Example

use zune_core::bytestream::ZByteReader;
let mut stream = ZByteReader::new([0x0,0x5,0x3,0x2].as_slice());
let first_bytes = stream.get_fixed_bytes_or_err::<10>(); // not enough bytes
assert!(first_bytes.is_err());

pub fn get_fixed_bytes_or_zero<const N: usize>(&mut self) -> [u8; N]

Get a fixed amount of bytes or return a zero array size if we can’t satisfy the read

This should be combined with has since if there are no more bytes you get a zero initialized array

For the error variant see, get_fixed_bytes_or_err

Example

use zune_core::bytestream::ZByteReader;
let mut stream = ZByteReader::new([0x0,0x5,0x3,0x2].as_slice());
let first_bytes = stream.get_fixed_bytes_or_zero::<2>();
assert_eq!(first_bytes,[0x0,0x5]);

pub fn skip_until_false<F: Fn(u8) -> bool>(&mut self, func: F)

Skip bytes until a condition becomes false or the stream runs out of bytes

Example

use zune_core::bytestream::ZByteReader;
let mut stream = ZByteReader::new([0;10].as_slice());
stream.skip_until_false(|x| x.is_ascii()) // skip until we meet a non ascii character

pub fn remaining_bytes(&self) -> &[u8]

Return the remaining unread bytes in this byte reader

pub fn read(&mut self, buf: &mut [u8]) -> Result<usize, &'static str>

pub fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), &'static str>

Read enough bytes to fill in

pub fn set_position(&mut self, position: usize)

Set the cursor position

After this, all reads will proceed from the position as an anchor point

impl<T> ZByteReader<T>

where T: ZReaderTrait,

pub fn get_u8(&mut self) -> u8

Retrieve a byte from the underlying stream returning 0 if there are no more bytes available

This means 0 might indicate a bit or an end of stream, but this is useful for some scenarios where one needs a byte.

For the panicking one, see get_u8_err

pub fn get_u8_err(&mut self) -> Result<u8, &'static str>

Retrieve a byte from the underlying stream returning an error if there are no more bytes available

For the non panicking one, see get_u8

impl<T: ZReaderTrait> ZByteReader<T>

pub fn get_u16_be_err(&mut self) -> Result<u16, &'static str>

Read u16 as a big endian integer Returning an error if the underlying buffer cannot support a u16 read.

pub fn get_u16_le_err(&mut self) -> Result<u16, &'static str>

Read u16 as a little endian integer Returning an error if the underlying buffer cannot support a u16 read.

pub fn get_u16_be(&mut self) -> u16

Read u16 as a big endian integer Returning 0 if the underlying buffer does not have enough bytes for a u16 read.

pub fn get_u16_le(&mut self) -> u16

Read u16 as a little endian integer Returning 0 if the underlying buffer does not have enough bytes for a u16 read.

impl<T: ZReaderTrait> ZByteReader<T>

pub fn get_u32_be_err(&mut self) -> Result<u32, &'static str>

Read u32 as a big endian integer Returning an error if the underlying buffer cannot support a u32 read.

pub fn get_u32_le_err(&mut self) -> Result<u32, &'static str>

Read u32 as a little endian integer Returning an error if the underlying buffer cannot support a u32 read.

pub fn get_u32_be(&mut self) -> u32

Read u32 as a big endian integer Returning 0 if the underlying buffer does not have enough bytes for a u32 read.

pub fn get_u32_le(&mut self) -> u32

Read u32 as a little endian integer Returning 0 if the underlying buffer does not have enough bytes for a u32 read.

impl<T: ZReaderTrait> ZByteReader<T>

pub fn get_u64_be_err(&mut self) -> Result<u64, &'static str>

Read u64 as a big endian integer Returning an error if the underlying buffer cannot support a u64 read.

pub fn get_u64_le_err(&mut self) -> Result<u64, &'static str>

Read u64 as a little endian integer Returning an error if the underlying buffer cannot support a u64 read.

pub fn get_u64_be(&mut self) -> u64

Read u64 as a big endian integer Returning 0 if the underlying buffer does not have enough bytes for a u64 read.

pub fn get_u64_le(&mut self) -> u64

Read u64 as a little endian integer Returning 0 if the underlying buffer does not have enough bytes for a u64 read.