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;
}

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 ‘one-shot’ only ever encodes a single symbol, and so does not need to encode an EOF symbol.

A one-shot Model is a special case of the fixed_length::Model.

A one-shot 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 one_shot::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
    }
}

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

Implementors