This release changes some trait bounds in the Rust API. It technically breaks backward compatibility (hence the bump in leading version number), but most projects will probably not notice these changes. Also, no "silent" changes are introduced, i.e., upgrading from `constriction` version 0.3 to this version (0.4) does not change compression behavior unless you decide to use any of the new features, so compressed data remains binary compatible.
However, after upgrading to this version, you might get some deprecation warnings (see details below) at compile time (in Rust) or at runtime (in Python). If you get such a warning, then it is highly recommended that you follow the upgrade instructions provided in the warnings because the *next* breaking version of `constriction` (version 0.5.0) will remove the deprecated methods from the Rust API, and it will change the default behavior of the Python constructor that currently prints a warning (thus breaking binary backward compatibility for compressed data).
New in This Release
- "Lazy" categorical distributions (`LazyContiguousCategoricalEntropyModel` in the Rust API, or `Categorical(..., lazy=True)` in the Python API) to significantly speed up compression and decompression with autoregressive models.
- For non-lazy categorical distributions, there is now a choice whether to construct them perfectly (as in version <= 0.3.5) or *very slightly* worse but potentially much faster (and compatibly with the "lazy" variant). To choose between the two, use the constructors `from_[symbols_and_]floating_point_probabilities_{perfect, fast}` in the Rust API, or `Categorical(..., perfect={True, False})` in the Python API).
Changes in This Release
- Increase minimum supported rust version (MSRV) to 1.75 (for return position `impl trait` in `trait`s), see below.
- The type signatures for lookup decoder models (Rust API only) was simplified. If your code uses lookup decoder models only via their type aliases (`Small[Non]ContiguousLookupDecoderModel`), then you probably won't notice this change.
- `IterableEntropyModel::symbol_table` now returns an anonymous type (`impl trait`). While this technically breaks edge cases, it is extremely unlikely to cause issues, and it significantly cleans up the public API.
Deprecation Warnings (And Changes Planned for the Next Breaking Release)
- In the Rust API, constructors for categorical distributions without the `..._fast` or `..._perfect` suffix are now deprecated. They currently forward to their respective `..._perfect` variant for backward compatibility, but they will be removed in the next breaking version of `constriction` (version 0.5) because the suggest a default that is probably a poor choice in most cases (the `..._fast` variant is a better choice for most new applications at this point).
- In the Python API, constructing a categorical distribution with neither of the optional parameters `fast` nor `perfect` set currently defaults to `perfect=True` for backward compatibility, but it prints a deprecation warning when called for the first time within a python session. The warning explains that the default will change to `perfect=False` in the next breaking version of `constriction` (version 0.5) as it is more likely the better choice.
- In the Python API, `constriction.symbol.{Queue, Stack}Coder.get_compressed` has been renamed to `get_compressed_and_bitrate` to avoid confusion about the return type. The old method currently still exists and forwards to the new method after printing a deprecation warning when called for the first time within a python session.