Trait Input

Source

pub trait Input {
    // Required methods
    fn remaining_len(&mut self) -> Result<Option<usize>, Error>;
    fn read(&mut self, into: &mut [u8]) -> Result<(), Error>;

    // Provided methods
    fn read_byte(&mut self) -> Result<u8, Error> { ... }
    fn descend_ref(&mut self) -> Result<(), Error> { ... }
    fn ascend_ref(&mut self) { ... }
    fn on_before_alloc_mem(&mut self, _size: usize) -> Result<(), Error> { ... }
}

Expand description

Trait that allows reading of data into a slice.

Required Methods§

Source

fn remaining_len(&mut self) -> Result<Option<usize>, Error>

Should return the remaining length of the input data. If no information about the input length is available, None should be returned.

The length is used to constrain the preallocation while decoding. Returning a garbage length can open the doors for a denial of service attack to your application. Otherwise, returning None can decrease the performance of your application.

Source

fn read(&mut self, into: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill the given buffer.

Note that this function is similar to std::io::Read::read_exact and not std::io::Read::read.

Provided Methods§

Source

fn read_byte(&mut self) -> Result<u8, Error>

Read a single byte from the input.

Source

fn descend_ref(&mut self) -> Result<(), Error>

Descend into nested reference when decoding. This is called when decoding a new refence-based instance, such as Vec or Box. Currently, all such types are allocated on the heap.

Source

fn ascend_ref(&mut self)

Ascend to previous structure level when decoding. This is called when decoding reference-based type is finished.

Source

fn on_before_alloc_mem(&mut self, _size: usize) -> Result<(), Error>

Hook that is called before allocating memory on the heap.

The aim is to get a reasonable approximation of memory usage, especially with variably sized types like Vecs. Depending on the structure, it is acceptable to be off by a bit. In some cases we might not track the memory used by internal sub-structures, and also we don’t take alignment or memory layouts into account. But we should always track the memory used by the decoded data inside the type.