Trait Model

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

    // Required methods
    fn probability(
        &self,
        symbol: &Self::Symbol,
    ) -> Result<Range<Self::B>, Self::ValueError>;
    fn max_denominator(&self) -> Self::B;
    fn symbol(&self, value: Self::B) -> Self::Symbol;
    fn 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 ‘fixed-length’ model always expects an exact number of symbols, and so does not need to encode an EOF symbol.

A fixed 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 fixed_length::Model for MyModel {
    type B = u32;
    type Symbol = Symbol;
    type ValueError = Infallible;

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

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

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

    fn 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: &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) -> 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 length(&self) -> usize

The total 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

impl<T> Model for T

where T: Model,

type B = <T as Model>::B

type Symbol = <T as Model>::Symbol

type ValueError = <T as Model>::ValueError