pub trait Source {
type Err: From<Error>;
fn request(&mut self, len: usize) -> Result<usize, Self::Err>;
fn advance(&mut self, len: usize) -> Result<(), Self::Err>;
fn slice(&self) -> &[u8] ⓘ;
fn bytes(&self, start: usize, end: usize) -> Bytes;
fn take_u8(&mut self) -> Result<u8, Self::Err> { ... }
fn take_opt_u8(&mut self) -> Result<Option<u8>, Self::Err> { ... }
}
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, advance forward, or advance forward returning a Bytes value of the data it advanced over.
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§
sourcetype Err: From<Error>
type Err: From<Error>
The error produced by the source.
The type used here needs to wrap ber::decode::Error
and extends it
by whatever happens if acquiring additional data fails. If Source
is implemented for types where this acqusition cannot fail,
ber::decode::Error
should be used here.
Required Methods§
sourcefn request(&mut self, len: usize) -> Result<usize, Self::Err>
fn request(&mut self, len: usize) -> Result<usize, Self::Err>
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.
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 advance(&mut self, len: usize) -> Result<(), Self::Err>
fn advance(&mut self, len: usize) -> Result<(), Self::Err>
Advance the source by len
bytes.
The method advances the start of the view provided by the source by
len
bytes. Advancing beyond the end of a source is an error.
Implementations should return their equivalient of
Error::Malformed
.
The value of len
may be larger than the last length previously
request via request
.
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 last
successful call to request
.