1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
//! Pure Rust Zstandard codec.
//!
//! `zstandard` implements the [Zstandard compression
//! format](https://datatracker.ietf.org/doc/html/rfc8878) without any C
//! dependency on the codec path. Frames produced by this crate decompress
//! cleanly with the official `zstd` library, and frames produced by `zstd`
//! decompress with this crate, for the format coverage implemented here.
//!
//! The crate is intentionally narrow: the public API exposes one-shot and
//! streaming encode/decode entry points, dictionary support, and a few
//! frame-level helpers. Internal encoder behavior — parser strategies, hash
//! tables, sequence statistics — is not part of the supported surface.
//!
//! # One-shot
//!
//! ```
//! use zstandard::{decode_all, encode_all};
//!
//! let compressed = encode_all(b"hello zstd")?;
//! assert_eq!(decode_all(&compressed)?, b"hello zstd");
//! # Ok::<(), zstandard::Error>(())
//! ```
//!
//! # Configurable encode
//!
//! [`EncoderOptions`] controls compression level, block size, content
//! checksum, and the frame header fields. [`CompressionLevel`] accepts the
//! range `-131072..=22`: `1..=22` selects progressively more thorough parsers,
//! and the negative levels are Zstandard's "fast mode", trading ratio for
//! speed below what level 1 does.
//!
//! ```
//! use zstandard::{CompressionLevel, EncoderOptions, decode_all, encode_all_with_options};
//!
//! let options = EncoderOptions {
//! compression_level: CompressionLevel::BETTER,
//! checksum: true,
//! ..Default::default()
//! };
//! let compressed = encode_all_with_options(b"compress me", options)?;
//! assert_eq!(decode_all(&compressed)?, b"compress me");
//! # Ok::<(), zstandard::Error>(())
//! ```
//!
//! For finer control, [`ParameterOverrides`] replaces individual compression
//! parameters that the level would otherwise choose — window and table sizes,
//! search depth, minimum match, target length, and the parser [`Strategy`].
//! Each parameter's accepted range is published as a [`ParameterBounds`]
//! constant, and a value outside it is reported rather than clamped.
//!
//! ```
//! use zstandard::{EncoderOptions, ParameterOverrides, Strategy, decode_all, encode_all_with_options};
//!
//! let options = EncoderOptions {
//! parameters: ParameterOverrides {
//! strategy: Some(Strategy::Lazy2),
//! window_log: Some(20),
//! ..Default::default()
//! },
//! ..Default::default()
//! };
//! let compressed = encode_all_with_options(b"a smaller window and a chosen parser", options)?;
//! assert_eq!(decode_all(&compressed)?, b"a smaller window and a chosen parser");
//! # Ok::<(), zstandard::Error>(())
//! ```
//!
//! # Dictionaries
//!
//! Both raw-content and formatted Zstandard dictionaries are supported, and a
//! parsed dictionary can be reused across many calls via
//! [`EncoderDictionary`] and [`DecoderDictionary`]. They are separate types
//! because the two directions need different tables built from the same bytes
//! and neither should carry the other's, which is the line upstream draws as
//! `ZSTD_CDict` and `ZSTD_DDict`; to use one dictionary both ways, build both
//! over the same `Arc<[u8]>`. [`train_dictionary`] builds one from sample data.
//!
//! ```
//! use zstandard::{decode_all_with_dict, encode_all_with_dict};
//!
//! let dictionary = b"shared prefix dictionary";
//! let payload = b"shared prefix dictionary + payload";
//!
//! let compressed = encode_all_with_dict(payload, dictionary)?;
//! assert_eq!(decode_all_with_dict(&compressed, dictionary)?, payload);
//! # Ok::<(), zstandard::Error>(())
//! ```
//!
//! # Streaming
//!
//! [`StreamingEncoder`] and [`StreamingDecoder`] consume input in chunks and
//! produce output progressively. Both contexts can be reused for additional
//! frames via `reset()` after `finish()`.
//!
//! ```
//! use zstandard::{DecoderOptions, EncoderOptions, StreamingDecoder, StreamingEncoder};
//!
//! let input = b"streaming example data".repeat(1_000);
//!
//! let mut encoder = StreamingEncoder::new(EncoderOptions::default())?;
//! let mut compressed = encoder.take_output();
//! for chunk in input.chunks(1_001) {
//! encoder.push(chunk)?;
//! compressed.extend_from_slice(&encoder.take_output());
//! }
//! encoder.finish()?;
//! compressed.extend_from_slice(&encoder.take_output());
//!
//! let mut decoder = StreamingDecoder::new(DecoderOptions::default());
//! let mut restored = Vec::new();
//! for chunk in compressed.chunks(113) {
//! decoder.push(chunk)?;
//! restored.extend_from_slice(&decoder.take_output());
//! }
//! decoder.finish()?;
//! restored.extend_from_slice(&decoder.take_output());
//! assert_eq!(restored, input);
//! # Ok::<(), zstandard::Error>(())
//! ```
//!
//! # `std::io` adapters
//!
//! [`io::Writer`] and [`io::Reader`] wrap the streaming contexts in the
//! `std::io` traits, so the codec composes with `io::copy`, `BufReader`, and
//! anything else that speaks `Read`/`Write`.
//!
//! ```
//! use std::io::{Read, Write};
//! use zstandard::io::{Reader, Writer};
//!
//! let mut writer = Writer::new(Vec::new())?;
//! writer.write_all(b"through std::io")?;
//! let compressed = writer.finish()?;
//!
//! let mut restored = Vec::new();
//! Reader::new(&compressed[..]).read_to_end(&mut restored)?;
//! assert_eq!(restored, b"through std::io");
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! # Errors
//!
//! All fallible operations return [`Result<T>`](Result) (alias for
//! `Result<T, Error>`). [`Error`] reports malformed input, configuration
//! mistakes, and decoder limits that the input would exceed; the decoder is
//! the security boundary, so soundness on adversarial input is treated as a
//! bug — see `SECURITY.md`.
//!
//! # Cargo features
//!
//! - `internal-trace` *(maintainer-only, hidden)* — enables block traces and
//! stage-profiling APIs used by the project's benchmark and parity tools.
//! Not part of the supported surface.
//! - `internal-fuzz` *(maintainer-only, hidden)* — enables a `fuzz` module
//! exposing internal entry points consumed by the fuzz harness.
//! - `asm-inspect` *(maintainer-only)* — enables an `asm_inspect` module of
//! `#[no_mangle]` shims used to inspect generated assembly.
//!
//! # MSRV
//!
//! Rust 1.96, as declared by `rust-version` in `Cargo.toml` and checked by CI.
//! The 2024 edition's own floor is 1.85; this crate's is higher.
// Not `pub`: these shims exist to put named symbols in `--emit asm` output,
// which `#[unsafe(no_mangle)]` guarantees on its own regardless of Rust
// visibility. Exporting them publicly bought nothing and leaked `BitDStream`,
// `DState` and `SequenceDecodeEntry` — all `pub(crate)` — through a public
// signature.
pub
// Compiles the README's Rust examples as doctests. They are the first code a
// newcomer runs, so they are held to the same standard as the examples in this
// file rather than being prose that happens to look like Rust. `cfg(doctest)`
// keeps the item out of every other build, including the rendered docs.
;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use LdmMode;
// Maintainer-only diagnostic surface: block traces, parser stats, and
// per-stage profiling. Hidden from rustdoc and from the default public API
// because the shapes are tied to internal encoder/decoder structure and
// change frequently. Enable the `internal-trace` feature to opt in.
pub use ;
pub use ;
pub use ;
pub use ;