zstd/stream/mod.rs
1//! Compress and decompress Zstd streams.
2//!
3//! Zstd streams are the main way to compress and decompress data.
4//! They are compatible with the `zstd` command-line tool.
5//!
6//! This module provides both `Read` and `Write` interfaces to compressing and
7//! decompressing.
8
9pub mod read;
10pub mod write;
11
12mod functions;
13pub mod zio;
14
15#[cfg(test)]
16mod tests;
17
18pub mod raw;
19
20pub use self::functions::{copy_decode, copy_encode, decode_all, encode_all};
21pub use self::read::Decoder;
22pub use self::write::{AutoFinishEncoder, Encoder};
23
24#[doc(hidden)]
25#[macro_export]
26/// Common functions for the decoder, both in read and write mode.
27macro_rules! decoder_parameters {
28 () => {
29 /// Sets the maximum back-reference distance.
30 ///
31 /// The actual maximum distance is going to be `2^log_distance`.
32 ///
33 /// This will need to at least match the value set when compressing.
34 pub fn window_log_max(&mut self, log_distance: u32) -> io::Result<()> {
35 self.set_parameter(zstd_safe::DParameter::WindowLogMax(
36 log_distance,
37 ))
38 }
39
40 #[cfg(feature = "experimental")]
41 #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
42 /// Enables or disabled expecting the 4-byte magic header
43 ///
44 /// Only available with the `experimental` feature.
45 ///
46 /// This will need to match the settings used when compressing.
47 pub fn include_magicbytes(
48 &mut self,
49 include_magicbytes: bool,
50 ) -> io::Result<()> {
51 self.set_parameter(zstd_safe::DParameter::Format(
52 if include_magicbytes {
53 zstd_safe::FrameFormat::One
54 } else {
55 zstd_safe::FrameFormat::Magicless
56 },
57 ))
58 }
59 };
60}
61
62#[doc(hidden)]
63#[macro_export]
64/// Common functions for the decoder, both in read and write mode.
65macro_rules! decoder_common {
66 ($readwrite:ident) => {
67 /// Sets a decompression parameter on the decompression stream.
68 pub fn set_parameter(
69 &mut self,
70 parameter: zstd_safe::DParameter,
71 ) -> io::Result<()> {
72 self.$readwrite.operation_mut().set_parameter(parameter)
73 }
74
75 $crate::decoder_parameters!();
76 };
77}
78
79#[doc(hidden)]
80#[macro_export]
81/// Parameter-setters for the encoder. Relies on a `set_parameter` method.
82macro_rules! encoder_parameters {
83 () => {
84 /// Controls whether zstd should include a content checksum at the end
85 /// of each frame.
86 pub fn include_checksum(
87 &mut self,
88 include_checksum: bool,
89 ) -> io::Result<()> {
90 self.set_parameter(zstd_safe::CParameter::ChecksumFlag(
91 include_checksum,
92 ))
93 }
94
95 /// Enables multithreaded compression
96 ///
97 /// * If `n_workers == 0` (default), then multithreaded will be
98 /// disabled.
99 /// * If `n_workers >= 1`, then compression will be done in separate
100 /// threads.
101 ///
102 /// So even `n_workers = 1` may increase performance by separating
103 /// IO and compression.
104 ///
105 /// Note: This is only available if the `zstdmt` cargo feature is activated.
106 #[cfg(feature = "zstdmt")]
107 #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "zstdmt")))]
108 pub fn multithread(&mut self, n_workers: u32) -> io::Result<()> {
109 self.set_parameter(zstd_safe::CParameter::NbWorkers(n_workers))
110 }
111
112 /// Enables or disables storing of the dict id.
113 ///
114 /// Defaults to true. If false, the behaviour of decoding with a wrong
115 /// dictionary is undefined.
116 pub fn include_dictid(
117 &mut self,
118 include_dictid: bool,
119 ) -> io::Result<()> {
120 self.set_parameter(zstd_safe::CParameter::DictIdFlag(
121 include_dictid,
122 ))
123 }
124
125 /// Enables or disabled storing of the contentsize.
126 ///
127 /// Note that this only has an effect if the size is given with `set_pledged_src_size`.
128 pub fn include_contentsize(
129 &mut self,
130 include_contentsize: bool,
131 ) -> io::Result<()> {
132 self.set_parameter(zstd_safe::CParameter::ContentSizeFlag(
133 include_contentsize,
134 ))
135 }
136 /// Enables or disables long-distance matching
137 pub fn long_distance_matching(
138 &mut self,
139 long_distance_matching: bool,
140 ) -> io::Result<()> {
141 self.set_parameter(
142 zstd_safe::CParameter::EnableLongDistanceMatching(
143 long_distance_matching,
144 ),
145 )
146 }
147
148 /// Sets the target size for compressed blocks.
149 ///
150 /// A lower block size may result in slightly lower speed (~2%) and compression ratio
151 /// (~0.1%), but may decrease end-to-end latency in low-bandwidth environments (time to
152 /// first decompressed byte).
153 ///
154 /// No value, or a value of zero, results in no contraint for the block sizes.
155 pub fn set_target_cblock_size(
156 &mut self,
157 target_size: Option<u32>,
158 ) -> io::Result<()> {
159 self.set_parameter(zstd_safe::CParameter::TargetCBlockSize(
160 target_size.unwrap_or(0),
161 ))
162 }
163
164 /// Sets the maximum back-reference distance.
165 ///
166 /// The actual maximum distance is going to be `2^log_distance`.
167 ///
168 /// Note that decompression will need to use at least the same setting.
169 pub fn window_log(&mut self, log_distance: u32) -> io::Result<()> {
170 self.set_parameter(zstd_safe::CParameter::WindowLog(log_distance))
171 }
172
173 #[cfg(feature = "experimental")]
174 #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
175 /// Enables or disable the magic bytes at the beginning of each frame.
176 ///
177 /// If disabled, include_magicbytes must also be called on the decoder.
178 ///
179 /// Only available with the `experimental` feature.
180 ///
181 /// Note that decompression will need to use the same setting.
182 pub fn include_magicbytes(
183 &mut self,
184 include_magicbytes: bool,
185 ) -> io::Result<()> {
186 self.set_parameter(zstd_safe::CParameter::Format(
187 if include_magicbytes {
188 zstd_safe::FrameFormat::One
189 } else {
190 zstd_safe::FrameFormat::Magicless
191 },
192 ))
193 }
194 };
195}
196
197#[doc(hidden)]
198#[macro_export]
199/// Common functions for the encoder, both in read and write mode.
200macro_rules! encoder_common {
201 ($readwrite:ident) => {
202 /// Sets the given zstd compression parameter.
203 pub fn set_parameter(
204 &mut self,
205 parameter: zstd_safe::CParameter,
206 ) -> io::Result<()> {
207 self.$readwrite.operation_mut().set_parameter(parameter)
208 }
209
210 /// Sets the expected size of the input.
211 ///
212 /// This affects the compression effectiveness.
213 ///
214 /// It is an error to give an incorrect size (an error will be returned when closing the
215 /// stream if the size does not match what was pledged).
216 ///
217 /// Giving a `None` size means the size is unknown (this is the default).
218 pub fn set_pledged_src_size(
219 &mut self,
220 size: Option<u64>,
221 ) -> io::Result<()> {
222 self.$readwrite.operation_mut().set_pledged_src_size(size)
223 }
224
225 $crate::encoder_parameters!();
226 };
227}