Struct flussab::ByteReader

pub struct ByteReader<'a> { /* fields omitted */ }

A buffered reader optimized for efficient parsing.

Like std’s BufReader, this provides buffering to coalesce many small reads into fewer larger reads of the underlying data source. The difference is that ByteReader is optimized for efficient parsing. This includes asynchronous handling of IO errors, position tracking, and dynamic contiguous look-ahead.

Implementations

impl<'a> ByteReader<'a>

pub fn from_buf_reader(buf_reader: BufReader<impl Read + 'a>) -> Self

Creates a ByteReader for the data of a BufReader.

pub fn from_read(read: impl Read + 'a) -> Self

Creates a ByteReader for the data of a Read instance.

If the Read instance is a BufReader, it is better to use from_buf_reader to avoid unnecessary double buffering of the data.

pub fn from_boxed_dyn_read(read: Box<dyn Read + 'a>) -> Self

Creates a ByteReader for the data of a boxed Read instance.

If the Read instance is a BufReader, it is better to use from_buf_reader to avoid unnecessary double buffering of the data.

pub fn set_chunk_size(&mut self, size: usize)

Sets the number of bytes that are read at once.

This sets the size of the read requests made. Note that this is just an upper bound. Depending on the Read implementation, smaller amounts may be read at once. To enable interactive line based input, ByteReader on its own will not issue more read requests than necessary.

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

Returns the currently buffered data in front of the cursor.

You can call is_complete to check whether the returned data contains all remaining input data.

pub fn buf_len(&self) -> usize

Returns the length of the currently buffered data.

This returns the same value as reader.buf().len() but unlike reader.buf() this does not create an intermediate reference to the buffered data. This can make a difference in safety when raw pointers are used to access the buffered data.

pub fn buf_ptr(&self) -> *const u8

Returns a pointer to the currently buffered data.

This returns the same value as reader.buf().as_ptr() but unlike reader.buf() this does not create an intermediate reference to the buffered data. You can use reader.buf_len() to obtain the length of the buffered data.

pub fn advance(&mut self, n: usize)

Advances the cursor by a given number of already buffered bytes.

This will panic if the number of bytes exceeds the amount of buffered data.

pub unsafe fn advance_unchecked(&mut self, n: usize)

Advances the cursor by a given number of already buffered bytes without checking if sufficient bytes are buffered.

Safety

The passed value for n may not exceed the value returned by buf_len().

pub fn position(&self) -> usize

Total number of bytes the cursor was advanced so far.

This wraps around every usize::MAX bytes.

pub fn mark(&self) -> usize

Returns currently marked position.

Initially this is position 0, but can be changed using set_mark and set_mark_to_position.

Setting the mark to the start of a token before advancing over it can be useful for error reporting.

pub fn set_mark(&mut self)

Marks the current position.

Calling this will make mark return the current position.

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

Sets the position returned by mark.

pub fn is_complete(&self) -> bool

Returns whether all remaining data is buffered.

If this returns true buf will contain all the remaining data. This can happen when the end was reached or when an IO error was encountered. You can use check_io_error to determine whether an IO error occured.

pub fn is_at_end(&self) -> bool

Returns whether the cursor is at the end of the available data.

This can be the end of the input or all data before an IO error was encountered. You can use check_io_error to determine whether an IO error occured.

pub fn check_io_error(&mut self) -> Result<()>

Returns an encountered IO errors as Err(io_err).

This resets the stored IO error and returns Ok(()) if no IO error is stored.

pub fn io_error(&self) -> Option<&Error>

Returns a reference to an encountered IO error.

This does not reset the stored IO error and erturns None if no IO error is stored.

pub fn request(&mut self, len: usize) -> &[u8]

Tries to extend the buffer by reading more data until it reaches the requested length.

Returns a slice to all of the buffered data, not only the requested amount.

This fails when the end of the input is reached or an IO error occured before enough data was read, in which case a smaller buffer than requested is returned.

pub fn request_byte(&mut self) -> Option<u8>

Tries to extend the buffer by reading more data until it contains at least one byte.

Returns the next byte.

This fails when the end of the input is reached or an IO error occured before enough data was read, in which case None is returned.

pub fn request_byte_at_offset(&mut self, offset: usize) -> Option<u8>

Tries to extend the buffer by reading more data until it contains at least the byte at the given offset from the current position.

Returns that byte.

This fails when the end of the input is reached or an IO error occured before enough data was read, in which case None is returned.

pub fn request_more(&mut self) -> bool

Tries to extend the buffer by reading more data.