Choose your API
Compression and decompression expose the same I/O shapes. Pick the row that matches how your application already moves bytes, then follow its guide. New to the crate? Start with getting started.
Both codecs
| I/O shape | Compression | Decompression | Guide |
|---|---|---|---|
Return a new Vec<u8> | Compressor::compress | Decompressor::decompress | Getting started |
| Append to an existing Vec | compress_into | decompress_into | Buffers and memory reuse |
| Write into a caller-owned slice | compress_to_slice, compress_to_uninit | decompress_to_slice, decompress_to_uninit | Buffers and memory reuse |
Pull output through std::io::Read | Compressor::reader | Decompressor::reader | Read / Write I/O |
Push input through std::io::Write | Compressor::writer | Decompressor::writer | Read / Write I/O |
| Drive input and output incrementally | start → EncoderSession | start → DecoderSession | Sans I/O compression, decompression |
| Same, with the session owning the codec | into_session → EncoderSessionOwned | into_session → DecoderSessionOwned | Sans I/O compression, decompression |
| Any of the above with a dictionary | compress_with_dictionary*, start_with_dictionary, into_session_with_dictionary, writer_with_dictionary, reader_with_dictionary | decompress_with_dictionary*, start_with_dictionary, into_session_with_dictionary, writer_with_dictionary, reader_with_dictionary | Dictionaries |
Compressor and Decompressor own reusable working state. Keep one alive
across payloads when allocation reuse matters.
Parallel compression
ParallelCompressor (in mzstd::compressor::parallel) is a separate execution
strategy for compression: it splits one frame into independent segments and
hands them to your executor as tasks. The library does not create a thread
pool. The output is a valid Zstandard frame, decoded by the ordinary
Decompressor. Requires std.
| I/O shape | Entry point |
|---|---|
| Split one known input across your threads | prepare_slice / prepare_source → ScopedParallelBatch |
| Stream chunked input across your threads | start → ParallelEncoderSession + ParallelTaskQueue |
| Same, with the session owning the compressor | into_session → ParallelEncoderSessionOwned |
Push or pull through std::io across your threads | writer, reader |
See parallel compression for scoped threads, Rayon, sources, staging, and streaming.
Guides by task
| Task | Read |
|---|---|
| Pick a level, parameters, or Cargo features | Configuration and features |
| Control allocations and retained memory | Buffers and memory reuse |
| Decode untrusted input with resource limits | Decompression and limits |
Understand readers, writers, sessions, and finish | Streaming and completion |
| Connect readers and writers for every format | Read / Write I/O |
| Drive compression with caller buffers | Sans I/O compression |
| Decode arriving chunks and resource events | Sans I/O decompression |
| Split a job across workers | Parallel compression |
| Package several resources | Framing containers |
| Share a dictionary or use magicless frames | Dictionaries and extended formats |
| Copy a complete program | Examples |
Errors
ConfigError covers encoder configuration, DecodeConfigError decoder limits,
DictionaryError dictionary preparation, and EncodeError / DecodeError
codec failures. Failed decoder calls report exact progress in DecodeFailure;
output delivered before final validation can be partial. I/O adapters return
std::io::Error, with the codec error as its source.
Reference
- API reference on docs.rs
- Compatibility and validation: what is byte-identical to zstd 1.5.7, and how it is checked
- Benchmark results for every measured level, with raw data
- Architecture: how the implementation works
- Development and benchmarking for contributors