Trait arithmetic_coding::max_length::Model

source · [−]
pub trait Model {
    type Symbol;
    type ValueError: Error;
    type B: BitStore = u32;

    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;

    fn denominator(&self) -> Self::B { ... }
    fn update(&mut self, _symbol: &Self::Symbol) { ... }
}
Expand description

A Model is used to calculate the probability of a given symbol occuring 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

#![feature(exclusive_range_pattern)]
#![feature(never_type)]

pub enum Symbol {
    A,
    B,
    C,
}

pub struct MyModel;

impl max_length::Model for MyModel {
    type Symbol = Symbol;
    type ValueError = !;

    fn probability(&self, symbol: Option<&Self::Symbol>) -> Result<Range<u32>, !> {
        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

The type of symbol this Model describes

Invalid symbol error

Provided Associated Types

The internal representation to use for storing integers

Required Methods

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

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.

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

None indicates EOF

This is the inverse of the Model::probability method

The maximum number of symbols to encode

Provided Methods

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.

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