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
//! Compress and decompress Zstd streams.
//!
//! Zstd streams are the main way to compress and decompress data.
//! They are compatible with the `zstd` command-line tool.
//!
//! This module provides both `Read` and `Write` interfaces to compressing and
//! decompressing.

pub mod read;
pub mod write;

mod functions;
pub mod zio;

#[cfg(test)]
mod tests;

pub mod raw;

pub use self::functions::{copy_decode, copy_encode, decode_all, encode_all};
pub use self::read::Decoder;
pub use self::write::{AutoFinishEncoder, Encoder};

#[doc(hidden)]
#[macro_export]
/// Common functions for the decoder, both in read and write mode.
macro_rules! decoder_parameters {
    () => {
        /// Sets the maximum back-reference distance.
        ///
        /// The actual maximum distance is going to be `2^log_distance`.
        ///
        /// This will need to at least match the value set when compressing.
        pub fn window_log_max(&mut self, log_distance: u32) -> io::Result<()> {
            self.set_parameter(zstd_safe::DParameter::WindowLogMax(
                log_distance,
            ))
        }

        #[cfg(feature = "experimental")]
        #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
        /// Enables or disabled expecting the 4-byte magic header
        ///
        /// Only available with the `experimental` feature.
        ///
        /// This will need to match the settings used when compressing.
        pub fn include_magicbytes(
            &mut self,
            include_magicbytes: bool,
        ) -> io::Result<()> {
            self.set_parameter(zstd_safe::DParameter::Format(
                if include_magicbytes {
                    zstd_safe::FrameFormat::One
                } else {
                    zstd_safe::FrameFormat::Magicless
                },
            ))
        }
    };
}

#[doc(hidden)]
#[macro_export]
/// Common functions for the decoder, both in read and write mode.
macro_rules! decoder_common {
    ($readwrite:ident) => {
        /// Sets a decompression parameter on the decompression stream.
        pub fn set_parameter(
            &mut self,
            parameter: zstd_safe::DParameter,
        ) -> io::Result<()> {
            self.$readwrite.operation_mut().set_parameter(parameter)
        }

        $crate::decoder_parameters!();
    };
}

#[doc(hidden)]
#[macro_export]
/// Parameter-setters for the encoder. Relies on a `set_parameter` method.
macro_rules! encoder_parameters {
    () => {
        /// Controls whether zstd should include a content checksum at the end
        /// of each frame.
        pub fn include_checksum(
            &mut self,
            include_checksum: bool,
        ) -> io::Result<()> {
            self.set_parameter(zstd_safe::CParameter::ChecksumFlag(
                include_checksum,
            ))
        }

        /// Enables multithreaded compression
        ///
        /// * If `n_workers == 0` (default), then multithreaded will be
        ///   disabled.
        /// * If `n_workers >= 1`, then compression will be done in separate
        ///   threads.
        ///
        /// So even `n_workers = 1` may increase performance by separating
        /// IO and compression.
        ///
        /// Note: This is only available if the `zstdmt` cargo feature is activated.
        #[cfg(feature = "zstdmt")]
        #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "zstdmt")))]
        pub fn multithread(&mut self, n_workers: u32) -> io::Result<()> {
            self.set_parameter(zstd_safe::CParameter::NbWorkers(n_workers))
        }

        /// Enables or disables storing of the dict id.
        ///
        /// Defaults to true. If false, the behaviour of decoding with a wrong
        /// dictionary is undefined.
        pub fn include_dictid(
            &mut self,
            include_dictid: bool,
        ) -> io::Result<()> {
            self.set_parameter(zstd_safe::CParameter::DictIdFlag(
                include_dictid,
            ))
        }

        /// Enables or disabled storing of the contentsize.
        ///
        /// Note that this only has an effect if the size is given with `set_pledged_src_size`.
        pub fn include_contentsize(
            &mut self,
            include_contentsize: bool,
        ) -> io::Result<()> {
            self.set_parameter(zstd_safe::CParameter::ContentSizeFlag(
                include_contentsize,
            ))
        }
        /// Enables or disables long-distance matching
        pub fn long_distance_matching(
            &mut self,
            long_distance_matching: bool,
        ) -> io::Result<()> {
            self.set_parameter(
                zstd_safe::CParameter::EnableLongDistanceMatching(
                    long_distance_matching,
                ),
            )
        }

        /// Sets the target size for compressed blocks.
        ///
        /// A lower block size may result in slightly lower speed (~2%) and compression ratio
        /// (~0.1%), but may decrease end-to-end latency in low-bandwidth environments (time to
        /// first decompressed byte).
        ///
        /// No value, or a value of zero, results in no contraint for the block sizes.
        pub fn set_target_cblock_size(
            &mut self,
            target_size: Option<u32>,
        ) -> io::Result<()> {
            self.set_parameter(zstd_safe::CParameter::TargetCBlockSize(
                target_size.unwrap_or(0),
            ))
        }

        /// Sets the maximum back-reference distance.
        ///
        /// The actual maximum distance is going to be `2^log_distance`.
        ///
        /// Note that decompression will need to use at least the same setting.
        pub fn window_log(&mut self, log_distance: u32) -> io::Result<()> {
            self.set_parameter(zstd_safe::CParameter::WindowLog(log_distance))
        }

        #[cfg(feature = "experimental")]
        #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
        /// Enables or disable the magic bytes at the beginning of each frame.
        ///
        /// If disabled, include_magicbytes must also be called on the decoder.
        ///
        /// Only available with the `experimental` feature.
        ///
        /// Note that decompression will need to use the same setting.
        pub fn include_magicbytes(
            &mut self,
            include_magicbytes: bool,
        ) -> io::Result<()> {
            self.set_parameter(zstd_safe::CParameter::Format(
                if include_magicbytes {
                    zstd_safe::FrameFormat::One
                } else {
                    zstd_safe::FrameFormat::Magicless
                },
            ))
        }
    };
}

#[doc(hidden)]
#[macro_export]
/// Common functions for the encoder, both in read and write mode.
macro_rules! encoder_common {
    ($readwrite:ident) => {
        /// Sets the given zstd compression parameter.
        pub fn set_parameter(
            &mut self,
            parameter: zstd_safe::CParameter,
        ) -> io::Result<()> {
            self.$readwrite.operation_mut().set_parameter(parameter)
        }

        /// Sets the expected size of the input.
        ///
        /// This affects the compression effectiveness.
        ///
        /// It is an error to give an incorrect size (an error will be returned when closing the
        /// stream if the size does not match what was pledged).
        ///
        /// Giving a `None` size means the size is unknown (this is the default).
        pub fn set_pledged_src_size(
            &mut self,
            size: Option<u64>,
        ) -> io::Result<()> {
            self.$readwrite.operation_mut().set_pledged_src_size(size)
        }

        $crate::encoder_parameters!();
    };
}