Struct constriction::stream::queue::RangeEncoder

pub struct RangeEncoder<Word, State, Backend = Vec<Word>>where
    Word: BitArray,
    State: BitArray,
    Backend: WriteWords<Word>,{ /* private fields */ }

Implementations

impl<Word, State> RangeEncoder<Word, State>where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,

pub fn new() -> Self

Creates an empty encoder for range coding.

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

pub fn with_backend(backend: Backend) -> Self

Assumes that the backend is in a state where the encoder can start writing as if it was an empty backend. If there’s already some compressed data on backend, then this method will just concatanate the new sequence of Words to the existing sequence of Words without gluing them together. This is likely not what you want since you won’t be able to decode the data in one go (however, it is Ok to concatenate arbitrary data to the output of a RangeEncoder; it won’t invalidate the existing data).

If you need an entropy coder that can be interrupted and serialized/deserialized (i.e., an encoder that can encode some symbols, return the compressed bit string as a sequence of Words, load the Words back in at a later point and then encode some more symbols), then consider using an AnsCoder.

TODO: rename to with_write_backend and then add the same method to AnsCoder

pub fn is_empty<'a>(&'a self) -> boolwhere
    Backend: AsReadWords<'a, Word, Queue>,
    Backend::AsReadWords: BoundedReadWords<Word, Queue>,

Check if no data has been encoded yet.

pub fn maybe_full(&self) -> bool

Same as Encoder::maybe_full, but can be called on a concrete type without type annotations.

pub fn into_decoder(
    self
) -> Result<RangeDecoder<Word, State, Backend::IntoReadWords>, ()>where
    Backend: IntoReadWords<Word, Queue>,

Same as IntoDecoder::into_decoder(self) but can be used for any PRECISION and therefore doesn’t require type arguments on the caller side.

TODO: there should also be a decoder() method that takes &mut self

pub fn into_compressed(self) -> Result<Backend, Backend::WriteError>

pub fn num_words<'a>(&'a self) -> usizewhere
    Backend: AsReadWords<'a, Word, Queue>,
    Backend::AsReadWords: BoundedReadWords<Word, Queue>,

Returns the number of compressed words on the ans.

This includes a constant overhead of between one and two words unless the coder is completely empty.

This method returns the length of the slice, the Vec<Word>, or the iterator that would be returned by get_compressed, into_compressed, or iter_compressed, respectively, when called at this time.

See also num_bits.

pub fn num_bits<'a>(&'a self) -> usizewhere
    Backend: AsReadWords<'a, Word, Queue>,
    Backend::AsReadWords: BoundedReadWords<Word, Queue>,

Returns the size of the current queue of compressed data in bits.

This includes some constant overhead unless the coder is completely empty (see num_words).

The returned value is a multiple of the bitlength of the compressed word type Word.

pub fn bulk(&self) -> &Backend

pub fn from_raw_parts(
    bulk: Backend,
    state: RangeCoderState<Word, State>,
    situation: EncoderSituation<Word>
) -> Self

Low-level constructor that assembles a RangeEncoder from its internal components.

The arguments bulk, state, and situation correspond to the three return values of the method into_raw_parts.

pub fn into_raw_parts(
    self
) -> (Backend, RangeCoderState<Word, State>, EncoderSituation<Word>)

Low-level method that disassembles the RangeEncoder into its internal components.

Can be used together with from_raw_parts.

impl<Word, State> RangeEncoder<Word, State>where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,

pub fn clear(&mut self)

Discards all compressed data and resets the coder to the same state as Coder::new.

pub fn get_compressed(&mut self) -> EncoderGuard<'_, Word, State>

Assembles the current compressed data into a single slice.

This method is only implemented for encoders backed by a Vec<Word> because we have to temporarily seal the encoder and then unseal it when the returned EncoderGuard is dropped, which requires precise knowledge of the backend (and which is also the reason why this method takes a &mut self receiver). If you’re using a different backend than a Vec, consider calling into_compressed instead.

pub fn decoder(
    &mut self
) -> RangeDecoder<Word, State, Cursor<Word, EncoderGuard<'_, Word, State>>>

A decoder for temporary use.

Once the returned decoder gets dropped, you can continue using this encoder. If you don’t need this flexibility, call into_decoder instead.

This method is only implemented for encoders backed by a Vec<Word> because we have to temporarily seal the encoder and then unseal it when the returned decoder is dropped, which requires precise knowledge of the backend (and which is also the reason why this method takes a &mut selfreceiver). If you’re using a different backend than a Vec, consider calling into_decoder instead.

Trait Implementations

impl<Word, State, Backend> Clone for RangeEncoder<Word, State, Backend>where
    Word: BitArray + Clone,
    State: BitArray + Clone,
    Backend: WriteWords<Word> + Clone,

fn clone(&self) -> RangeEncoder<Word, State, Backend>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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>

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

type Word = Word

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).

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

Returns the current internal state of the coder.

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

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

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

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

impl<Word, State, Backend> Debug for RangeEncoder<Word, State, Backend>where
    Word: BitArray + Debug,
    State: BitArray + Debug,
    Backend: WriteWords<Word> + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

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

fn default() -> Self

This is essentially the same as #[derive(Default)], except for the assertions on State::BITS and Word::BITS.

impl<Word, State, Backend, const PRECISION: usize> Encode<PRECISION> for RangeEncoder<Word, State, Backend>where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,
    Backend: WriteWords<Word>,

type FrontendError = DefaultEncoderFrontendError

The error type for logical encoding errors.

type BackendError = <Backend as WriteWords<Word>>::WriteError

The error type for writing out encoded data.

fn encode_symbol<D>(
    &mut self,
    symbol: impl Borrow<D::Symbol>,
    model: D
) -> Result<(), CoderError<DefaultEncoderFrontendError, Self::BackendError>>where
    D: EncoderModel<PRECISION>,
    D::Probability: Into<Self::Word>,
    Self::Word: AsPrimitive<D::Probability>,

Encodes a single symbol with the given entropy model.

fn maybe_full(&self) -> bool

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

fn encode_symbols<S, M>(
    &mut self,
    symbols_and_models: impl IntoIterator<Item = (S, M)>
) -> Result<(), CoderError<Self::FrontendError, Self::BackendError>>where
    S: Borrow<M::Symbol>,
    M: EncoderModel<PRECISION>,
    M::Probability: Into<Self::Word>,
    Self::Word: AsPrimitive<M::Probability>,

Encodes a sequence of symbols, each with its individual entropy model.

fn try_encode_symbols<S, M, E>(
    &mut self,
    symbols_and_models: impl IntoIterator<Item = Result<(S, M), E>>
) -> Result<(), TryCodingError<CoderError<Self::FrontendError, Self::BackendError>, E>>where
    S: Borrow<M::Symbol>,
    M: EncoderModel<PRECISION>,
    M::Probability: Into<Self::Word>,
    Self::Word: AsPrimitive<M::Probability>,

Encodes a sequence of symbols from a fallible iterator.

fn encode_iid_symbols<S, M>(
    &mut self,
    symbols: impl IntoIterator<Item = S>,
    model: M
) -> Result<(), CoderError<Self::FrontendError, Self::BackendError>>where
    S: Borrow<M::Symbol>,
    M: EncoderModel<PRECISION> + Copy,
    M::Probability: Into<Self::Word>,
    Self::Word: AsPrimitive<M::Probability>,

Encodes a sequence of symbols, all with the same entropy model.

impl<Word, State, Backend> From<RangeEncoder<Word, State, Backend>> for RangeDecoder<Word, State, Backend::IntoReadWords>where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,
    Backend: WriteWords<Word> + IntoReadWords<Word, Queue>,

fn from(encoder: RangeEncoder<Word, State, Backend>) -> Self

Converts to this type from the input type.

impl<Word, State> From<RangeEncoder<Word, State, Vec<Word, Global>>> for Vec<Word>where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,

fn from(val: RangeEncoder<Word, State>) -> Self

Converts to this type from the input type.

impl<Word, State, Backend, const PRECISION: usize> IntoDecoder<PRECISION> for RangeEncoder<Word, State, Backend>where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,
    Backend: WriteWords<Word> + IntoReadWords<Word, Queue>,

type IntoDecoder = RangeDecoder<Word, State, <Backend as IntoReadWords<Word, Queue>>::IntoReadWords>

The target type of the conversion.

fn into_decoder(self) -> Self::IntoDecoder

Performs the conversion.

impl<Word, State, Backend> Pos for RangeEncoder<Word, State, Backend>where
    Word: BitArray + Into<State>,
    State: BitArray + AsPrimitive<Word>,
    Backend: WriteWords<Word> + Pos<Position = usize>,

fn pos(&self) -> Self::Position

Returns the position in the compressed data, in units of Words.

impl<Word, State, Backend> PosSeek for RangeEncoder<Word, State, Backend>where
    Word: BitArray,
    State: BitArray,
    Backend: WriteWords<Word> + PosSeek,
    Self: Code,

type Position = (<Backend as PosSeek>::Position, <RangeEncoder<Word, State, Backend> as Code>::State)