Trait bcder::decode::Source

source ·

pub trait Source {
    type Error: Error;

    // Required methods
    fn pos(&self) -> Pos;
    fn request(&mut self, len: usize) -> Result<usize, Self::Error>;
    fn slice(&self) -> &[u8] ⓘ;
    fn bytes(&self, start: usize, end: usize) -> Bytes;
    fn advance(&mut self, len: usize);

    // Provided methods
    fn skip(&mut self, len: usize) -> Result<usize, Self::Error> { ... }
    fn take_u8(&mut self) -> Result<u8, DecodeError<Self::Error>> { ... }
    fn take_opt_u8(&mut self) -> Result<Option<u8>, Self::Error> { ... }
    fn content_err(
        &self,
        err: impl Into<ContentError>
    ) -> DecodeError<Self::Error> { ... }
}

Expand description

A view into a sequence of octets.

Sources form that foundation of decoding. They provide the raw octets to decoders.

A source can only progress forward over time. It provides the ability to access the next few bytes as a slice or a Bytes value, and advance forward.

Please note: This trait may change as we gain more experience with decoding in different circumstances. If you implement it for your own types, we would appreciate feedback what worked well and what didn’t.

Required Associated Types§

source

type Error: Error

The error produced when the source failed to read more data.

Required Methods§

source

fn pos(&self) -> Pos

Returns the current logical postion within the sequence of data.

source

fn request(&mut self, len: usize) -> Result<usize, Self::Error>

Request at least len bytes to be available.

The method returns the number of bytes that are actually available. This may only be smaller than len if the source ends with less bytes available. It may be larger than len but less than the total number of bytes still left in the source.

The method can be called multiple times without advancing in between. If in this case len is larger than when last called, the source should try and make the additional data available.

The method should only return an error if the source somehow fails to get more data such as an IO error or reset connection.

source

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

Returns a bytes slice with the available data.

The slice will be at least as long as the value returned by the last successful request call. It may be longer if more data is available.

source

fn bytes(&self, start: usize, end: usize) -> Bytes

Produces a Bytes value from part of the data.

The method returns a Bytes value of the range start..end from the beginning of the current view of the source. Both indexes must not be greater than the value returned by the last successful call to request.

Panics

The method panics if start or end are larger than the result of the last successful call to request.

source

fn advance(&mut self, len: usize)

Advance the source by len bytes.

The method advances the start of the view provided by the source by len bytes. This value must not be greater than the value returned by the last successful call to request.

Panics

The method panics if len is larger than the result of the last successful call to request.

Provided Methods§

source

fn skip(&mut self, len: usize) -> Result<usize, Self::Error>

Skip over the next len bytes.

The method attempts to advance the source by len bytes or by however many bytes are still available if this number is smaller, without making these bytes available.

Returns the number of bytes skipped over. This value may only differ from len if the remainder of the source contains less than len bytes.

The default implementation uses request and advance. However, for some sources it may be significantly cheaper to provide a specialised implementation.

source