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§
Required Methods§
sourcefn request(&mut self, len: usize) -> Result<usize, Self::Error>
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.
sourcefn slice(&self) -> &[u8] ⓘ
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.
sourcefn bytes(&self, start: usize, end: usize) -> Bytes
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
.
sourcefn advance(&mut self, len: usize)
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§
sourcefn skip(&mut self, len: usize) -> Result<usize, Self::Error>
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.
sourcefn take_u8(&mut self) -> Result<u8, DecodeError<Self::Error>>
fn take_u8(&mut self) -> Result<u8, DecodeError<Self::Error>>
Takes a single octet from the source.
If there aren’t any more octets available from the source, returns a content error.
sourcefn take_opt_u8(&mut self) -> Result<Option<u8>, Self::Error>
fn take_opt_u8(&mut self) -> Result<Option<u8>, Self::Error>
Takes an optional octet from the source.
If there aren’t any more octets available from the source, returns
Ok(None)
.
sourcefn content_err(&self, err: impl Into<ContentError>) -> DecodeError<Self::Error>
fn content_err(&self, err: impl Into<ContentError>) -> DecodeError<Self::Error>
Returns a content error at the current position of the source.