Trait Model

pub trait Model {
    type Symbol;
    type ValueError: Error;
    type B: BitStore;

    // Required methods
    fn probability(
        &self,
        symbol: Option<&Self::Symbol>,
    ) -> Result<Range<Self::B>, Self::ValueError>;
    fn max_denominator(&self) -> Self::B;
    fn symbol(&self, value: Self::B) -> Option<Self::Symbol>;
    fn max_length(&self) -> usize;

    // Provided methods
    fn denominator(&self) -> Self::B { ... }
    fn update(&mut self, _symbol: &Self::Symbol) { ... }
}

A Model is used to calculate the probability of a given symbol occurring in a sequence.

The Model is used both for encoding and decoding. A ‘max-length’ model has a maximum length. The compressed size of a message equal to the maximum length is larger than with a fixed_length::Model, but smaller than with a Model.

A max-length model can be converted into a regular model using the convenience Wrapper type.

The more accurately a Model is able to predict the next symbol, the greater the compression ratio will be.

Example

pub enum Symbol {
    A,
    B,
    C,
}

pub struct MyModel;

impl max_length::Model for MyModel {
    type B = u32;
    type Symbol = Symbol;
    type ValueError = Infallible;

    fn probability(&self, symbol: Option<&Self::Symbol>) -> Result<Range<u32>, Infallible> {
        Ok(match symbol {
            Some(Symbol::A) => 0..1,
            Some(Symbol::B) => 1..2,
            Some(Symbol::C) => 2..3,
            None => 3..4,
        })
    }

    fn symbol(&self, value: Self::B) -> Option<Self::Symbol> {
        match value {
            0..1 => Some(Symbol::A),
            1..2 => Some(Symbol::B),
            2..3 => Some(Symbol::C),
            3..4 => None,
            _ => unreachable!(),
        }
    }

    fn max_denominator(&self) -> u32 {
        4
    }

    fn max_length(&self) -> usize {
        3
    }
}

Required Associated Types

type Symbol

The type of symbol this Model describes

type ValueError: Error

Invalid symbol error

type B: BitStore

The internal representation to use for storing integers

Required Methods

fn probability( &self, symbol: Option<&Self::Symbol>, ) -> Result<Range<Self::B>, Self::ValueError>

Given a symbol, return an interval representing the probability of that symbol occurring.

This is given as a range, over the denominator given by Model::denominator. This range should in general include EOF, which is denoted by None.

For example, from the set {heads, tails}, the interval representing heads could be 0..1, and tails would be 1..2, and EOF could be 2..3 (with a denominator of 3).

This is the inverse of the Model::symbol method

Errors

This returns a custom error if the given symbol is not valid

fn max_denominator(&self) -> Self::B

The maximum denominator used for probability ranges. See Model::probability.

This value is used to calculate an appropriate precision for the encoding, therefore this value must not change, and Model::denominator must never exceed it.

fn symbol(&self, value: Self::B) -> Option<Self::Symbol>

Given a value, return the symbol whose probability range it falls in.

None indicates EOF

This is the inverse of the Model::probability method

fn max_length(&self) -> usize

The maximum number of symbols to encode

Provided Methods

fn denominator(&self) -> Self::B

The denominator for probability ranges. See Model::probability.

By default this method simply returns the Model::max_denominator, which is suitable for non-adaptive models.

In adaptive models this value may change, however it should never exceed Model::max_denominator, or it becomes possible for the Encoder and Decoder to panic due to overflow or underflow.

fn update(&mut self, _symbol: &Self::Symbol)

Update the current state of the model with the latest symbol.

This method only needs to be implemented for ‘adaptive’ models. It’s a no-op by default.

Implementors