Skip to main content

async_compression/
macros.rs

1macro_rules! algos {
2    (@algo $algo:ident [$algo_s:expr] $(#[cfg($extra_cfg:meta)])? $decoder:ident $encoder:ident <$inner:ident>
3        { @enc $($encoder_methods:tt)* }
4        { @dec $($decoder_methods:tt)* }
5    ) => {
6        #[cfg(all(feature = $algo_s $(, $extra_cfg)?))]
7        decoder! {
8            #[doc = concat!("A ", $algo_s, " decoder, or decompressor")]
9            #[cfg(all(feature = $algo_s $(, $extra_cfg)?))]
10            $decoder<$inner>
11
12            { $($decoder_methods)* }
13        }
14
15        #[cfg(all(feature = $algo_s $(, $extra_cfg)?))]
16        encoder! {
17            #[doc = concat!("A ", $algo_s, " encoder, or compressor.")]
18            #[cfg(all(feature = $algo_s $(, $extra_cfg)?))]
19            $encoder<$inner> {
20                pub fn new(inner: $inner) -> Self {
21                    Self::with_quality(inner, crate::core::Level::Default)
22                }
23            }
24
25            { $($encoder_methods)* }
26        }
27    };
28
29    (@algo $algo:ident [$algo_s:expr] $decoder:ident $encoder:ident <$inner:ident>
30        { @dec $($decoder_methods:tt)* }
31    ) => {
32        #[cfg(feature = $algo_s)]
33        decoder! {
34            #[doc = concat!("A ", $algo_s, " decoder, or decompressor")]
35            #[cfg(feature = $algo_s)]
36            $decoder<$inner>
37
38            { $($decoder_methods)* }
39        }
40    };
41
42    ($($mod:ident)::+ <$inner:ident>) => {
43        algos!(@algo brotli ["brotli"] BrotliDecoder BrotliEncoder <$inner>
44        { @enc
45            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
46                // let params = brotli::enc::backward_references::BrotliEncoderParams::default();
47                let params = crate::codecs::brotli::params::EncoderParams::default();
48                let params = params.quality(level);
49                Self {
50                    inner: crate::$($mod::)+generic::Encoder::new(
51                        inner,
52                        crate::codecs::BrotliEncoder::new(params),
53                    ),
54                }
55            }
56
57            /// Creates a new encoder, using the specified compression level and parameters, which
58            /// will read uncompressed data from the given stream and emit a compressed stream.
59            pub fn with_params(
60                inner: $inner,
61                params: crate::codecs::brotli::params::EncoderParams,
62            ) -> Self {
63                Self {
64                    inner: crate::$($mod::)+generic::Encoder::new(
65                        inner,
66                        crate::codecs::BrotliEncoder::new(params),
67                    ),
68                }
69            }
70        }
71        { @dec }
72        );
73
74        algos!(@algo brotli ["brotli-mbrotli"] #[cfg(async_compression_unstable)] MbrotliDecoder MbrotliEncoder <$inner>
75        { @enc
76            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
77                let params = crate::codecs::mbrotli::params::EncoderParams::default();
78                let params = params.quality(level);
79                Self::with_params(
80                    inner,
81                    params,
82                )
83            }
84
85            /// Creates a new encoder, using the specified compression level and parameters, which
86            /// will read uncompressed data from the given stream and emit a compressed stream.
87            pub fn with_params(
88                inner: $inner,
89                params: crate::codecs::mbrotli::params::EncoderParams,
90            ) -> Self {
91                Self {
92                    inner: crate::$($mod::)+generic::Encoder::new(
93                        inner,
94                        crate::codecs::MbrotliEncoder::new(params),
95                    ),
96                }
97            }
98        }
99        { @dec }
100        );
101
102        algos!(@algo bzip2 ["bzip2"] BzDecoder BzEncoder <$inner>
103        { @enc
104
105            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
106                let params = crate::codecs::bzip2::params::Bzip2EncoderParams::from(level);
107                Self {
108                    inner: crate::$($mod::)+generic::Encoder::new(
109                        inner,
110                        crate::codecs::BzEncoder::new(params, 0),
111                    ),
112                }
113            }
114        }
115        { @dec }
116        );
117
118        algos!(@algo deflate ["deflate"] DeflateDecoder DeflateEncoder <$inner>
119        { @enc
120            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
121                let mut params = crate::codecs::flate::params::FlateEncoderParams::from(level);
122
123                Self {
124                    inner: crate::$($mod::)+generic::Encoder::new(
125                        inner,
126                        crate::codecs::DeflateEncoder::new(params),
127                    ),
128                }
129            }
130
131            /// Returns the total number of input bytes which have been processed by this compression object.
132            pub fn total_in(&self) -> u64 {
133                self.inner.get_encoder_ref().get_ref().get_ref().total_in()
134            }
135
136            /// Returns the total number of output bytes which have been produced by this compression object.
137            pub fn total_out(&self) -> u64 {
138                self.inner.get_encoder_ref().get_ref().get_ref().total_out()
139            }
140        }
141        { @dec }
142        );
143
144        algos!(@algo deflate ["deflate64"] Deflate64Decoder Deflate64Encoder <$inner>
145        { @dec }
146        );
147
148        algos!(@algo gzip ["gzip"] GzipDecoder GzipEncoder <$inner>
149        { @enc
150
151            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
152                let params = crate::codecs::flate::params::FlateEncoderParams::from(level);
153                Self {
154                    inner: crate::$($mod::)+generic::Encoder::new(
155                        inner,
156                        crate::codecs::GzipEncoder::new(params),
157                    ),
158                }
159            }
160        }
161        { @dec }
162        );
163
164        algos!(@algo zlib ["zlib"] ZlibDecoder ZlibEncoder <$inner>
165        { @enc
166            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
167                  let params = crate::codecs::flate::params::FlateEncoderParams::from(level);
168                Self {
169                    inner: crate::$($mod::)+generic::Encoder::new(
170                        inner,
171                        crate::codecs::ZlibEncoder::new(params),
172                    ),
173                }
174            }
175
176            /// Returns the total number of input bytes which have been processed by this compression object.
177            pub fn total_in(&self) -> u64 {
178                self.inner.get_encoder_ref().get_ref().get_ref().total_in()
179            }
180
181            /// Returns the total number of output bytes which have been produced by this compression object.
182            pub fn total_out(&self) -> u64 {
183                self.inner.get_encoder_ref().get_ref().get_ref().total_out()
184            }
185        }
186        { @dec }
187        );
188
189        algos!(@algo zstd ["zstd"] ZstdDecoder ZstdEncoder <$inner>
190        { @enc
191
192            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
193                let params = crate::codecs::zstd::params::CParameter::quality(level);
194                Self {
195                    inner: crate::$($mod::)+generic::Encoder::new(
196                        inner,
197                        crate::codecs::ZstdEncoder::new(params),
198                    ),
199                }
200            }
201
202            /// Creates a new encoder, using the specified compression level and parameters, which
203            /// will read uncompressed data from the given stream and emit a compressed stream.
204            ///
205            /// # Panics
206            ///
207            /// Panics if this function is called with a [`CParameter::nb_workers()`] parameter and
208            /// the `zstdmt` crate feature is _not_ enabled.
209            ///
210            /// [`CParameter::nb_workers()`]: crate::codecs::zstd::params::CParameter
211            //
212            // TODO: remove panic note on next breaking release, along with `CParameter::nb_workers`
213            // change
214            pub fn with_quality_and_params(inner: $inner, level: crate::core::Level, params: &[crate::codecs::zstd::params::CParameter]) -> Self {
215                let level = crate::codecs::zstd::params::CParameter::quality(level);
216                Self {
217                    inner: crate::$($mod::)+generic::Encoder::new(
218                        inner,
219                        crate::codecs::ZstdEncoder::new_with_params(level, params),
220                    ),
221                }
222            }
223
224            /// Creates a new encoder, using the specified compression level and pre-trained
225            /// dictionary, which will read uncompressed data from the given stream and emit a
226            /// compressed stream.
227            ///
228            /// Dictionaries provide better compression ratios for small files, but are required to
229            /// be present during decompression.
230            ///
231            /// # Errors
232            ///
233            /// Returns error when `dictionary` is not valid.
234            pub fn with_dict(inner: $inner, level: crate::core::Level, dictionary: &[u8]) -> ::std::io::Result<Self> {
235                let level = crate::codecs::zstd::params::CParameter::quality(level);
236                Ok(Self {
237                    inner: crate::$($mod::)+generic::Encoder::new(
238                        inner,
239                        crate::codecs::ZstdEncoder::new_with_dict(level, dictionary)?,
240                    ),
241                })
242            }
243        }
244        { @dec
245            /// Creates a new decoder, using the specified parameters, which will read compressed
246            /// data from the given stream and emit a decompressed stream.
247            pub fn with_params(inner: $inner, params: &[crate::codecs::zstd::params::DParameter]) -> Self {
248                Self {
249                    inner: crate::$($mod::)+generic::Decoder::new(
250                        inner,
251                        crate::codecs::ZstdDecoder::new_with_params(params),
252                    ),
253                }
254            }
255
256            /// Creates a new decoder, using the specified compression level and pre-trained
257            /// dictionary, which will read compressed data from the given stream and emit an
258            /// uncompressed stream.
259            ///
260            /// Dictionaries provide better compression ratios for small files, but are required to
261            /// be present during decompression. The dictionary used must be the same as the one
262            /// used for compression.
263            ///
264            /// # Errors
265            ///
266            /// Returns error when `dictionary` is not valid.
267            pub fn with_dict(inner: $inner, dictionary: &[u8]) -> ::std::io::Result<Self> {
268                Ok(Self {
269                    inner: crate::$($mod::)+generic::Decoder::new(
270                        inner,
271                        crate::codecs::ZstdDecoder::new_with_dict(dictionary)?,
272                    ),
273                })
274            }
275        }
276        );
277
278        algos!(@algo zstd ["zstd-mzstd"] #[cfg(async_compression_unstable)] MzstdDecoder MzstdEncoder <$inner>
279        { @enc
280
281            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
282                let params = crate::codecs::mzstd::params::CParameter::quality(level);
283                Self::with_codec(inner, crate::codecs::MzstdEncoder::new(params))
284            }
285
286            /// Creates a new encoder, using the specified compression level and parameters, which
287            /// will read uncompressed data from the given stream and emit a compressed stream.
288            ///
289            /// # Panics
290            ///
291            /// Panics if a parameter is out of range.
292            pub fn with_quality_and_params(inner: $inner, level: crate::core::Level, params: &[crate::codecs::mzstd::params::CParameter]) -> Self {
293                let level = crate::codecs::mzstd::params::CParameter::quality(level);
294                Self::with_codec(inner, crate::codecs::MzstdEncoder::new_with_params(level, params))
295            }
296
297            /// Creates a new encoder, using the specified compression level and pre-trained
298            /// dictionary, which will read uncompressed data from the given stream and emit a
299            /// compressed stream.
300            ///
301            /// Dictionaries provide better compression ratios for small files, but are required to
302            /// be present during decompression.
303            ///
304            /// # Errors
305            ///
306            /// Returns error when `dictionary` is not valid.
307            pub fn with_dict(inner: $inner, level: crate::core::Level, dictionary: &[u8]) -> ::std::io::Result<Self> {
308                let level = crate::codecs::mzstd::params::CParameter::quality(level);
309                Ok(Self::with_codec(inner, crate::codecs::MzstdEncoder::new_with_dict(level, dictionary)?))
310            }
311        }
312        { @dec
313            /// Creates a new decoder, using the specified parameters, which will read compressed
314            /// data from the given stream and emit a decompressed stream.
315            ///
316            /// # Panics
317            ///
318            /// Panics if a parameter is out of range.
319            pub fn with_params(inner: $inner, params: &[crate::codecs::mzstd::params::DParameter]) -> Self {
320                Self::with_codec(inner, crate::codecs::MzstdDecoder::new_with_params(params))
321            }
322
323            /// Creates a new decoder, using the specified pre-trained dictionary, which will read
324            /// compressed data from the given stream and emit an uncompressed stream.
325            ///
326            /// Dictionaries provide better compression ratios for small files, but are required to
327            /// be present during decompression. The dictionary used must be the same as the one
328            /// used for compression.
329            ///
330            /// # Errors
331            ///
332            /// Returns error when `dictionary` is not valid.
333            pub fn with_dict(inner: $inner, dictionary: &[u8]) -> ::std::io::Result<Self> {
334                Ok(Self::with_codec(inner, crate::codecs::MzstdDecoder::new_with_dict(dictionary)?))
335            }
336        }
337        );
338
339        algos!(@algo xz ["xz"] XzDecoder XzEncoder <$inner>
340        { @enc
341
342            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
343                Self {
344                    inner: crate::$($mod::)+generic::Encoder::new(
345                        inner,
346                        crate::codecs::XzEncoder::new(level),
347                    ),
348                }
349            }
350
351            /// Creates a new multi-threaded encoder.
352            ///
353            /// Note that flushing will severely impact multi-threaded performance.
354            #[cfg(feature = "xz-parallel")]
355            pub fn parallel(inner: $inner, level: crate::core::Level, threads: std::num::NonZeroU32) -> Self {
356                Self {
357                    inner: crate::$($mod::)+generic::Encoder::new(
358                        inner,
359                        crate::codecs::XzEncoder::parallel(threads, level),
360                    ),
361                }
362            }
363        }
364        { @dec
365            /// Creates a new decoder with the specified limit of memory.
366            ///
367            /// # Errors
368            ///
369            /// An IO error may be returned during decoding if the specified limit is too small.
370            pub fn with_mem_limit(read: $inner, memlimit: u64) -> Self {
371                Self {
372                    inner: crate::$($mod::)+generic::Decoder::new(
373                        read,
374                        crate::codecs::XzDecoder::with_memlimit(memlimit),
375                    ),
376                }
377            }
378
379            /// Creates a new multi-threaded decoder.
380            #[cfg(feature = "xz-parallel")]
381            pub fn parallel(read: $inner, threads: std::num::NonZeroU32) -> Self {
382                use std::convert::TryInto;
383
384                Self {
385                    inner: crate::$($mod::)+generic::Decoder::new(
386                        read,
387                        crate::codecs::XzDecoder::parallel(threads, usize::MAX.try_into().unwrap()),
388                    ),
389                }
390            }
391
392            /// Creates a new multi-threaded decoder with the specified limit of memory.
393            ///
394            /// # Errors
395            ///
396            /// An IO error may be returned during decoding if the specified limit is too small.
397            #[cfg(feature = "xz-parallel")]
398            pub fn parallel_with_mem_limit(read: $inner, threads: std::num::NonZeroU32, memlimit: u64) -> Self {
399                Self {
400                    inner: crate::$($mod::)+generic::Decoder::new(
401                        read,
402                        crate::codecs::XzDecoder::parallel(threads, memlimit),
403                    ),
404                }
405            }
406        }
407        );
408
409        algos!(@algo lzma ["lzma"] LzmaDecoder LzmaEncoder <$inner>
410        { @enc
411
412            pub fn with_quality(inner: $inner, level:  crate::core::Level) -> Self {
413                let encoder = crate::codecs::LzmaEncoder::new(level);
414                let inner =  crate::$($mod::)+generic::Encoder::new(inner, encoder);
415                Self {
416                    inner
417                }
418            }
419        }
420        { @dec
421            /// Creates a new decoder with the specified limit of memory.
422            ///
423            /// # Errors
424            ///
425            /// An IO error may be returned during decoding if the specified limit is too small.
426            pub fn with_mem_limit(read: $inner, memlimit: u64) -> Self {
427                Self {
428                    inner: crate::$($mod::)+generic::Decoder::new(
429                        read,
430                        crate::codecs::LzmaDecoder::with_memlimit(memlimit),
431                    ),
432                }
433            }
434
435        }
436        );
437
438        algos!(@algo lz4 ["lz4"] Lz4Decoder Lz4Encoder <$inner>
439        { @enc
440
441            pub fn with_quality(inner: $inner, level: crate::core::Level) -> Self {
442                Self::with_quality_and_params(inner, level, crate::codecs::lz4::params::EncoderParams::default())
443            }
444
445            /// Creates a new encoder, using the specified compression level and parameters, which
446            /// will read uncompressed data from the given stream and emit a compressed stream.
447            pub fn with_quality_and_params(
448                inner: $inner,
449                level: crate::core::Level,
450                mut params: crate::codecs::lz4::params::EncoderParams,
451            ) -> Self {
452                let params = params.level(level);
453                let encoder = crate::codecs::Lz4Encoder::new(params);
454                let cap = encoder.buffer_size();
455                Self {
456                    inner: crate::$($mod::)+generic::Encoder::with_capacity(
457                        inner,
458                        encoder,
459                        cap,
460                    ),
461                }
462            }
463        }
464        { @dec }
465        );
466
467    }
468}