Trait Encoder

Source

pub trait Encoder {
    // Required methods
    fn current_chunk(&self) -> &[u8] ⓘ;
    fn advance(&mut self) -> EncoderStatus;
}

Expand description

An encoder for a consensus-encodable object.

The consumers of a type implementing this encoder trait should generally use it in a loop like this:

loop {
    process_current_chunk(encoder.current_chunk());
    if encoder.advance().is_finished() {
        break
    }
}
// do NOT use encoder after this point

Processing the chunks in an equivalent state machine (presumably future) is also permissible.

It is crucial that the callers use the methods in that order: obtain the slice via current_chunk, write it somewhere and, once fully written, try to advance the encoder. Attempting to call any method after advance returned EncoderStatus::Finished or calling advance before fully processing the chunks will lead to unspecified buggy behavior.

The callers MUST NOT assume that the encoder returns any particular size of the chunks. The implementors are allowed to change the sizes of the chunks as long as the concatenation of all the bytes returned stays the same.

Required Methods§

Source

fn current_chunk(&self) -> &[u8] ⓘ

Yields the current encoded byte slice.

Will always return the same value until Self::advance is called. May return an empty slice, however implementors should avoid returning empty slices unless the encoded type is truly empty.

Source

fn advance(&mut self) -> EncoderStatus

Moves the encoder to its next state.

Does not need to be called when the encoder is first created. (In fact, if it is called, this will discard the first chunk of encoded data.)

§Returns

EncoderStatus::HasMore if the encoder has advanced to a new state and Self::current_chunk will return new data.
EncoderStatus::Finished if the encoder is exhausted and has no more states.

§Important

After EncoderStatus::Finished was returned the encoder is in unspecified state. Calling any of its methods in such state is a bug (but not UB) unless the specific encoder documents otherwise. While usually the encoder simply stays in the last possible state this MUST NOT be relied upon by the callers.