Trait packet::records::RecordsCounter
source · pub trait RecordsCounter: Sized {
type TooFewRecordsErr;
// Required method
fn next_lowest_value(&self) -> Option<Self>;
// Provided method
fn result_for_end_of_records(&self) -> Result<(), Self::TooFewRecordsErr> { ... }
}Expand description
A counter used to keep track of how many records are remaining to be parsed.
Some record sequence formats include an indication of how many records
should be expected. For example, the IGMPv3 Membership Report Message
includes a “Number of Group Records” field in its header which indicates how
many Group Records are present following the header. A RecordsCounter is a
type used by these protocols to keep track of how many records are remaining
to be parsed. It is implemented for all unsigned numeric primitive types
(usize, u8, u16, u32, u64, and u128). A no-op implementation
which does not track the number of remaining records is provided for ().
Required Associated Types§
sourcetype TooFewRecordsErr
type TooFewRecordsErr
The error returned from result_for_end_of_records when fewer records
were found than expected.
Some formats which store the number of records out-of-band consider it
an error to provide fewer records than this out-of-band value.
TooFewRecordsErr is the error returned by
result_for_end_of_records when this condition is encountered. If the
number of records is not tracked (usually, when Self = ()) or if it is
not an error to provide fewer records than expected, it is recommended
that TooFewRecordsErr be set to an uninhabited type like Never.
Required Methods§
sourcefn next_lowest_value(&self) -> Option<Self>
fn next_lowest_value(&self) -> Option<Self>
Gets the next lowest value unless the counter is already at 0.
During parsing, this value will be queried prior to parsing a record. If
the counter has already reached zero (next_lowest_value returns
None), parsing will be terminated. If the counter has not yet reached
zero and a record is successfully parsed, the previous counter value
will be overwritten with the one provided by next_lowest_value. In
other words, the parsing logic will look something like the following
pseudocode:
let next = counter.next_lowest_value()?;
let record = parse()?;
*counter = next;If Self is a type which does not impose a limit on the number of
records parsed (usually, ()), next_lowest_value must always return
Some. The value contained in the Some is irrelevant - it will just
be written back verbatim after a record is successfully parsed.
Provided Methods§
sourcefn result_for_end_of_records(&self) -> Result<(), Self::TooFewRecordsErr>
fn result_for_end_of_records(&self) -> Result<(), Self::TooFewRecordsErr>
Gets a result which can be used to determine whether it is an error that there are no more records left to parse.
Some formats which store the number of records out-of-band consider it
an error to provide fewer records than this out-of-band value.
result_for_end_of_records is called when there are no more records
left to parse. If the counter is still at a non-zero value, and the
protocol considers this to be an error, result_for_end_of_records
should return an appropriate error. Otherwise, it should return
Ok(()).