Expand description
Safe Rust Zstandard (RFC 8878) codecs.
The encoder is a port of the reference implementation, zstd 1.5.7, and writes the same bytes it does; the decoder reads every frame RFC 8878 defines, with or without a dictionary.
§Byte identity
For the same input and parameters, single-threaded compression produces
exactly the bytes of zstd 1.5.7: one-shot compression matches
ZSTD_compress2, and an encoder session matches ZSTD_compressStream2
driven with the same input chunks, output capacities and operations. The
contract covers compression levels -131072 to 22, the explicit
compression parameters (window, hash, chain and search logs, minimum
match, target length, strategy), long distance matching, the checksum and
content-size flags, declared input sizes, size hints, and raw-content and
Zstandard-format dictionaries (dictionary), which match the reference
after ZSTD_CCtx_loadDictionary_advanced.
Parallel compression writes valid frames that decode to the input but are
not those of the reference’s multithreaded mode. The magicless format,
targetCBlockSize and external sequence producers are not supported.
§Choose your API
Compression and decompression expose the same core I/O shapes. Pick the shape that
matches how your application already moves bytes. ParallelCompressor is a separate
execution strategy for compression: it splits one frame into independent segments and
hands them to your executor as tasks, either for a whole input at once or for input
that arrives in chunks. Each codec requires its Cargo feature; reader/writer adapters
and parallel compression are unavailable with no_std.
| I/O shape | Compression | Decompression |
|---|---|---|
Return a new Vec<u8> | Compressor::compress | Decompressor::decompress |
| Append to an existing Vec | compress_into | decompress_into |
| Write into a caller-owned slice | compress_to_slice, compress_to_uninit | decompress_to_slice |
Pull output through std::io::Read | Compressor::reader | Decompressor::reader |
Push input through std::io::Write | Compressor::writer | Decompressor::writer |
| Drive input/output incrementally | start → EncoderSession | start → DecoderSession |
| Same, with the session owning the codec | into_session → EncoderSessionOwned | into_session → DecoderSessionOwned |
| Split one known input across your threads | prepare_slice → 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 | — |
Each compression and decompression shape has a _with_dictionary form
that takes a dictionary from dictionary.
EncoderConfig selects the level and frame flags, and
CompressionParams overrides individual parameters exactly as
ZSTD_CCtx_setParameter would. DecodeLimits bound the window, input
and output, so untrusted frames cannot make the decoder allocate without
limit.
use mzstd::{Compressor, Decompressor, EncoderConfig, Level};
let mut encoder = Compressor::new(EncoderConfig::default().with_level(Level::try_from(19)?))?;
let payload = "the quick brown fox ".repeat(500);
let compressed = encoder.compress(payload.as_bytes())?;
assert!(compressed.len() < payload.len() / 50);
assert_eq!(Decompressor::default().decompress(&compressed)?, payload.as_bytes());§Select only the codecs you need
The default feature set is std, compression, and decompression. Disable default
features to select one codec, alongside std or no_std (which needs alloc):
mzstd = { version = "0.2", default-features = false, features = ["std", "decompression"] }A disabled codec has no module and no re-exports. The std::io adapters
and parallel compression need std.
Re-exports§
pub use compressor::CompressionParams;pub use compressor::Compressor;pub use compressor::CompressorBuilder;pub use compressor::ConfigError;pub use compressor::EncodeError;pub use compressor::EncoderConfig;pub use compressor::EncoderSession;pub use compressor::EncoderSessionOwned;pub use compressor::EncoderStatus;pub use compressor::InputSize;pub use compressor::LdmParams;pub use compressor::Level;pub use compressor::LongDistanceMatching;pub use compressor::Operation;pub use compressor::Parameter;pub use compressor::Progress;pub use compressor::SizeOverflow;pub use compressor::Strategy;pub use compressor::StreamConfig;pub use decompressor::DecodeConfigError;pub use decompressor::DecodeError;pub use decompressor::DecodeFailure;pub use decompressor::DecodeLimits;pub use decompressor::DecodeOperation;pub use decompressor::DecodeProgress;pub use decompressor::DecoderConfig;pub use decompressor::DecoderSession;pub use decompressor::DecoderSessionOwned;pub use decompressor::DecoderStatus;pub use decompressor::Decompressor;pub use decompressor::DecompressorBuilder;pub use decompressor::FrameMode;pub use decompressor::InvalidDataKind;
Modules§
- compressor
- Zstandard compression.
- decompressor
- Zstandard (RFC 8878) decompression.
- dictionary
- Zstandard dictionaries.
- io
- Streaming I/O adapters for compression and decompression.
Structs§
- Backend
- A supported execution backend: the SIMD instruction level the codecs’ kernels run with.
Enums§
- Retention
Policy - What a codec keeps allocated between operations.