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§

source

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§

source

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§

source

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(()).

Implementations on Foreign Types§

source§

impl RecordsCounter for u8

source§

impl RecordsCounter for usize

source§

impl RecordsCounter for u128

source§

impl RecordsCounter for u64

source§

impl RecordsCounter for ()

source§

impl RecordsCounter for u32

source§

impl RecordsCounter for u16

Implementors§