Trait constriction::stream::Code

pub trait Code {
    type Word: BitArray;
    type State: Clone;
    fn state(&self) -> Self::State;

    fn encoder_maybe_full<const PRECISION: usize>(&self) -> bool
    where
        Self: Encode<PRECISION>,
    { ... }
    fn decoder_maybe_exhausted<const PRECISION: usize>(&self) -> bool
    where
        Self: Decode<PRECISION>,
    { ... }
}

Base trait for stream encoders and decoders

This trait has to be implemented by all stream encoders and decoders. In addition, you’ll likely want to implement at least one of the Encode and Decode trait. While some stream coders may implement both Encode and Decode for the same type (e.g., AnsCoder and ChainCoder if the default backends are used), others, like the RangeEncoder and RangeDecoder provide different types that specialize for encoding or decoding only.

This trait defines the Word and State types, which apply to both encoding and decoding.

Naming Convention

This trait is deliberately called Code (as in the verb “to code”) and not Coder so that the term Coder can still be used for generic type parameters without leading to confusion with trait bounds. For example, you may want to write impl Wrapper<Coder> where Coder: Code. Using the verb for trait names and the noun for types has precedence in the standard library: see, e.g., the BufRead trait, which is implemented by the BufReader type.

Associated Types

type Word: BitArray

The smallest unit of compressed data that this coder can emit or read at once. Most coders guarantee that encoding emits at most one Word per symbol (plus a constant overhead).

type State: Clone

The internal coder state, as returned by the method state.

This internal coder state is relevant if the coder implements Pos and/or Seek. By convention, Pos::pos returns a tuple (pos, state) where pos represents the position in the backend(s) while state is the internal coder state.

Most implementations of Code are generic over a type parameter State. Note that, while the associated type Code::State is typically related to the type parameter State, they do not necessarily need to be the same. For example, in a RangeEncoder, the associated type <RangeEncoder as Code>::State is a struct of type RangeCoderState, which has twice the size of the type parameter State (same for RangeDecoder).

Required methods

fn state(&self) -> Self::State

Returns the current internal state of the coder.

This method returns only the “frontend” state. If you also need the backend state, i.e., the current position of the coder in the stream of compressed data, then call Pos::pos (which is typically only available if the backend(s) implement Pos).

Provided methods

fn encoder_maybe_full<const PRECISION: usize>(&self) -> bool where
    Self: Encode<PRECISION>, 

Checks if there might not be any room to encode more data.

This is a convenience forwarding method to simplify type annotations. In the default implementation, calling encoder.encoder_maybe_full::<PRECISION>() is equivalent to Encode::<PRECISION>::maybe_full(&encoder). See Encode::maybe_full.

fn decoder_maybe_exhausted<const PRECISION: usize>(&self) -> bool where
    Self: Decode<PRECISION>, 

Checks if there might be no compressed data left for decoding.

This is a convenience forwarding method to simplify type annotations. In the default implementation, calling decoder.decoder_maybe_exhausted::<PRECISION>() is equivalent to Decode::<PRECISION>::maybe_exhausted(&decoder). See Decode::maybe_exhausted.

Implementors

impl<Word, State, Backend> Code for RangeDecoder<Word, State, Backend> where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,
    Backend: ReadWords<Word, Queue>, 

type State = RangeCoderState<Word, State>

type Word = Word

fn state(&self) -> Self::State

impl<Word, State, Backend> Code for RangeEncoder<Word, State, Backend> where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,
    Backend: WriteWords<Word>, 

type State = RangeCoderState<Word, State>

type Word = Word

fn state(&self) -> Self::State

impl<Word, State, Backend> Code for AnsCoder<Word, State, Backend> where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>, 

type Word = Word

type State = State

fn state(&self) -> Self::State

impl<Word, State, CompressedBackend, RemainingBackend, const PRECISION: usize> Code for ChainCoder<Word, State, CompressedBackend, RemainingBackend, PRECISION> where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>, 

type Word = Word

type State = ChainCoderHeads<Word, State, PRECISION>

fn state(&self) -> Self::State