Trait constriction::stream::model::DecoderModel
source · pub trait DecoderModel<const PRECISION: usize>: EntropyModel<PRECISION> {
// Required method
fn quantile_function(
&self,
quantile: Self::Probability
) -> (Self::Symbol, Self::Probability, <Self::Probability as BitArray>::NonZero);
}Expand description
A trait for EntropyModels that can be used for decoding (decompressing) data.
As discussed in the module level documentation, all stream codes in
constriction use so-called EntropyModels for encoding and/or decoding data. Some
of these EntropyModels may be used only for encoding, only for decoding, or for both,
depending on their internal representation.
This DecoderModel trait is implemented for all entropy models that can be used for
decoding data. To decode data with a DecoderModel, construct an entropy coder that
implements the Decode trait and pass the entropy model to one of the methods of the
Decode trait.
Blanket Implementation for &impl DecoderModel
We provide the following blanket implementation for references to DecoderModels:
impl<M, const PRECISION: usize> DecoderModel<PRECISION> for &M
where
M: DecoderModel<PRECISION> + ?Sized
{ ... }This means that, if some type M implements DecoderModel<PRECISION> for some
PRECISION, then so does the reference type &M. Therefore, generic functions or
methods should never take a generic DecoderModel by reference. They should always take
the generic DecoderModel by value because this also covers the case of references
but is strictly more general. If your generic function needs to be able to cheaply copy
the DecoderModel (as it could with a shared reference) then it should still take the
generic DecoderModel formally by value and just add an additional Copy bound (see,
e.g., the method signature of Decode::decode_iid_symbols. For a more elaborate
explanation, please refer to the discussion of the analogous blanket implementation for
EntropyModel.
See Also
- base trait:
EntropyModel - sister trait:
EncoderModel - used with:
Decode
Required Methods§
sourcefn quantile_function(
&self,
quantile: Self::Probability
) -> (Self::Symbol, Self::Probability, <Self::Probability as BitArray>::NonZero)
fn quantile_function( &self, quantile: Self::Probability ) -> (Self::Symbol, Self::Probability, <Self::Probability as BitArray>::NonZero)
Looks up the symbol for a given quantile.
The argument quantile represents a number in the half-open interval [0, 1) in
fixed-point arithmetic, i.e., it must be strictly smaller than 1 << PRECISION.
Think of quantile as a point on the vertical axis of a plot of the cumulative
distribution function of the probability model. This method evaluates the inverse of
the cumulative distribution function, which is sometimes called the quantile
function.
Returns a tuple (symbol, left_sided_cumulative, probability) where probability
is the probability of symbol under the entropy model (in fixed-point arithmetic)
and left_sided_cumulative is the sum of the probabilities of all symbols up to and
not including symbol. The returned symbol is the unique symbol that satisfies
left_sided_cumulative <= quantile < left_sided_cumulative + probability (where the
addition on the right-hand side is non-wrapping).
Note that, in contrast to EncoderModel::left_cumulative_and_probability, this
method does not return an Option. This is because, as long as quantile < 1 << PRECISION, a valid probability distribution always has a symbol for which the range
left_sided_cumulative..(left_sided_cumulative + quantile) contains quantile, and
the probability of this symbol is guaranteed to be nonzero because the probability
is the size of the range, which contains at least the one element quantile.
Panics
Implementations may panic if quantile >= 1 << PRECISION.