Examples
The recipes below include complete programs and round-trip assertions. Examples
use the default std, compression, and decompression features unless stated
otherwise. The documentation workflow compiles and runs their Rust code against
the current checkout.
| Task | Recipe | Features / extra dependency |
|---|---|---|
| Compress and decompress bytes | First round trip | Default |
| Reuse codec and destination memory | Reuse the workspace | Default |
| Pick a level and explicit parameters | Choose a level first | Default |
| Write into a caller-owned slice | Output buffers | Default |
| Decode untrusted input with limits | Set limits for untrusted input | Default |
| Compress small records with a dictionary | Prepared dictionaries | Default |
| Write a raw stream incrementally | Stream through Write | Default |
| Drive a raw or framed encoder with tiny buffers | Sans I/O compression | Default; framed for frames |
| Decode arriving chunks and resource events | Sans I/O decompression | Default; framed for frames |
| Read or write raw, parallel, and framed streams | Read / Write I/O | Default; framed for frames |
| Use scoped CPU workers | Compressing a slice | Default |
| Reuse a Rayon thread pool | Running tasks with Rayon | Default + rayon |
| Stream through parallel workers | Reader and writer adapters | Default |
| Package compressed and stored resources | One container, two resources | framed |
| Add resource names and write incrementally | Write resources and metadata | framed |
| Read just the selected resource | Indexed resource reads | framed |
Run from the repository
The runnable user recipes are complete programs embedded in the guides. To compile and run all of them against this checkout:
python3 scripts/docs.py test-examples
The repository also provides a profiling driver:
git submodule update --init --recursive
cargo run --release --example profile_compressor -- testdata/alice29.txt
See benchmarking for profiling options and the C comparison.
For a parallel batch, all taken tasks must run or be dropped before finalization. For a streaming adapter, keep workers running while the adapter blocks. For writers, finish each resource and the enclosing stream or container explicitly.
Verify the documented recipes
python3 scripts/docs.py test-examples
This creates a temporary Cargo consumer under target/, depends on the local
crate with framed enabled and on Rayon, and runs each fenced Rust program
from the recipe guides: getting started, configuration, buffers, decompression,
streaming, parallel, frames, Sans I/O compression/decompression, the I/O
guide, and dictionaries. It does not
exercise the codec with --all-features, because that would also enable no_std
and remove the std APIs these recipes demonstrate.