Debian Codegraph @

.cargo/vendor/flate2/src/lib.rs

raw
1 //! A DEFLATE-based stream compression/decompression library
2 //!
3 //! This library provides support for compression and decompression of
4 //! DEFLATE-based streams:
5 //!
6 //! * the DEFLATE format itself
7 //! * the zlib format
8 //! * gzip
9 //!
10 //! These three formats are all closely related and largely only differ in their
11 //! headers/footers. This crate has three types in each submodule for dealing
12 //! with these three formats.
13 //!
14 //! # Implementation
15 //!
16 //! In addition to supporting three formats, this crate supports several different
17 //! backends, controlled through this crate's features:
18 //!
19 //! * `default`, or `rust_backend` - this implementation uses the `miniz_oxide`
20 //! crate which is a port of `miniz.c` to Rust. This feature does not
21 //! require a C compiler, and only uses safe Rust code.
22 //!
23 //! * `zlib-rs` - this implementation utilizes the `zlib-rs` crate, a Rust rewrite of zlib.
24 //! This backend is the fastest, at the cost of some `unsafe` Rust code.
25 //!
26 //! Several backends implemented in C are also available.
27 //! These are useful in case you are already using a specific C implementation
28 //! and need the result of compression to be bit-identical.
29 //! See the crate's README for details on the available C backends.
30 //!
31 //! The `zlib-rs` backend typically outperforms all the C implementations.
32 //!
33 //! # Organization
34 //!
35 //! This crate consists mainly of three modules, [`read`], [`write`], and
36 //! [`bufread`]. Each module contains a number of types used to encode and
37 //! decode various streams of data.
38 //!
39 //! All types in the [`write`] module work on instances of [`Write`][write],
40 //! whereas all types in the [`read`] module work on instances of
41 //! [`Read`][read] and [`bufread`] works with [`BufRead`][bufread]. If you
42 //! are decoding directly from a `&[u8]`, use the [`bufread`] types.
43 //!
44 //! ```
45 //! use flate2::write::GzEncoder;
46 //! use flate2::Compression;
47 //! use std::io;
48 //! use std::io::prelude::*;
49 //!
50 //! # fn main() { let _ = run(); }
51 //! # fn run() -> io::Result<()> {
52 //! let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
53 //! encoder.write_all(b"Example")?;
54 //! # Ok(())
55 //! # }
56 //! ```
57 //!
58 //!
59 //! Other various types are provided at the top-level of the crate for
60 //! management and dealing with encoders/decoders. Also note that types which
61 //! operate over a specific trait often implement the mirroring trait as well.
62 //! For example a `flate2::read::DeflateDecoder<T>` *also* implements the
63 //! `Write` trait if `T: Write`. That is, the "dual trait" is forwarded directly
64 //! to the underlying object if available.
65 //!
66 //! # About multi-member Gzip files
67 //!
68 //! While most `gzip` files one encounters will have a single *member* that can be read
69 //! with the [`GzDecoder`], there may be some files which have multiple members.
70 //!
71 //! A [`GzDecoder`] will only read the first member of gzip data, which may unexpectedly
72 //! provide partial results when a multi-member gzip file is encountered. `GzDecoder` is appropriate
73 //! for data that is designed to be read as single members from a multi-member file. `bufread::GzDecoder`
74 //! and `write::GzDecoder` also allow non-gzip data following gzip data to be handled.
75 //!
76 //! The [`MultiGzDecoder`] on the other hand will decode all members of a `gzip` file
77 //! into one consecutive stream of bytes, which hides the underlying *members* entirely.
78 //! If a file contains non-gzip data after the gzip data, MultiGzDecoder will
79 //! emit an error after decoding the gzip data. This behavior matches the `gzip`,
80 //! `gunzip`, and `zcat` command line tools.
81 //!
82 //! [`read`]: read/index.html
83 //! [`bufread`]: bufread/index.html
84 //! [`write`]: write/index.html
85 //! [read]: https://doc.rust-lang.org/std/io/trait.Read.html
86 //! [write]: https://doc.rust-lang.org/std/io/trait.Write.html
87 //! [bufread]: https://doc.rust-lang.org/std/io/trait.BufRead.html
88 //! [`GzDecoder`]: read/struct.GzDecoder.html
89 //! [`MultiGzDecoder`]: read/struct.MultiGzDecoder.html
90 #![doc(html_root_url = "https://docs.rs/flate2/0.2")]
91 #![deny(missing_docs)]
92 #![deny(missing_debug_implementations)]
93 #![allow(trivial_numeric_casts)]
94 #![cfg_attr(test, deny(warnings))]
95 #![cfg_attr(docsrs, feature(doc_cfg))]
96
97 #[cfg(not(feature = "any_impl",))]
98 compile_error!("You need to choose a zlib backend");
99
100 pub use crate::crc::{Crc, CrcReader, CrcWriter};
101 pub use crate::gz::GzBuilder;
102 pub use crate::gz::GzHeader;
103 pub use crate::mem::{Compress, CompressError, Decompress, DecompressError, Status};
104 pub use crate::mem::{FlushCompress, FlushDecompress};
105
106 mod bufreader;
107 mod crc;
108 mod deflate;
109 mod ffi;
110 mod gz;
111 mod mem;
112 mod zio;
113 mod zlib;
114
115 /// Types which operate over [`Read`] streams, both encoders and decoders for
116 /// various formats.
117 ///
118 /// Note that the `read` decoder types may read past the end of the compressed
119 /// data while decoding. If the caller requires subsequent reads to start
120 /// immediately following the compressed data wrap the `Read` type in a
121 /// [`BufReader`] and use the `BufReader` with the equivalent decoder from the
122 /// `bufread` module and also for the subsequent reads.
123 ///
124 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
125 /// [`BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html
126 pub mod read {
127 pub use crate::deflate::read::DeflateDecoder;
128 pub use crate::deflate::read::DeflateEncoder;
129 pub use crate::gz::read::GzDecoder;
130 pub use crate::gz::read::GzEncoder;
131 pub use crate::gz::read::MultiGzDecoder;
132 pub use crate::zlib::read::ZlibDecoder;
133 pub use crate::zlib::read::ZlibEncoder;
134 }
135
136 /// Types which operate over [`Write`] streams, both encoders and decoders for
137 /// various formats.
138 ///
139 /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
140 pub mod write {
141 pub use crate::deflate::write::DeflateDecoder;
142 pub use crate::deflate::write::DeflateEncoder;
143 pub use crate::gz::write::GzDecoder;
144 pub use crate::gz::write::GzEncoder;
145 pub use crate::gz::write::MultiGzDecoder;
146 pub use crate::zlib::write::ZlibDecoder;
147 pub use crate::zlib::write::ZlibEncoder;
148 }
149
150 /// Types which operate over [`BufRead`] streams, both encoders and decoders for
151 /// various formats.
152 ///
153 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
154 pub mod bufread {
155 pub use crate::deflate::bufread::DeflateDecoder;
156 pub use crate::deflate::bufread::DeflateEncoder;
157 pub use crate::gz::bufread::GzDecoder;
158 pub use crate::gz::bufread::GzEncoder;
159 pub use crate::gz::bufread::MultiGzDecoder;
160 pub use crate::zlib::bufread::ZlibDecoder;
161 pub use crate::zlib::bufread::ZlibEncoder;
162 }
163
164 fn _assert_send_sync() {
165 fn _assert_send_sync<T: Send + Sync>() {}
166
167 _assert_send_sync::<read::DeflateEncoder<&[u8]>>();
168 _assert_send_sync::<read::DeflateDecoder<&[u8]>>();
169 _assert_send_sync::<read::ZlibEncoder<&[u8]>>();
170 _assert_send_sync::<read::ZlibDecoder<&[u8]>>();
171 _assert_send_sync::<read::GzEncoder<&[u8]>>();
172 _assert_send_sync::<read::GzDecoder<&[u8]>>();
173 _assert_send_sync::<read::MultiGzDecoder<&[u8]>>();
174 _assert_send_sync::<write::DeflateEncoder<Vec<u8>>>();
175 _assert_send_sync::<write::DeflateDecoder<Vec<u8>>>();
176 _assert_send_sync::<write::ZlibEncoder<Vec<u8>>>();
177 _assert_send_sync::<write::ZlibDecoder<Vec<u8>>>();
178 _assert_send_sync::<write::GzEncoder<Vec<u8>>>();
179 _assert_send_sync::<write::GzDecoder<Vec<u8>>>();
180 }
181
182 /// When compressing data, the compression level can be specified by a value in
183 /// this struct.
184 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
185 pub struct Compression(u32);
186
187 impl Compression {
188 /// Creates a new description of the compression level with an explicitly
189 /// specified integer.
190 ///
191 /// The integer here is typically on a scale of 0-9 where 0 means "no
192 /// compression" and 9 means "take as long as you'd like".
193 pub const fn new(level: u32) -> Compression {
194 Compression(level)
195 }
196
197 /// No compression is to be performed, this may actually inflate data
198 /// slightly when encoding.
199 pub const fn none() -> Compression {
200 Compression(0)
201 }
202
203 /// Optimize for the best speed of encoding.
204 pub const fn fast() -> Compression {
205 Compression(1)
206 }
207
208 /// Optimize for the size of data being encoded.
209 pub const fn best() -> Compression {
210 Compression(9)
211 }
212
213 /// Returns an integer representing the compression level, typically on a
214 /// scale of 0-9. See [`new`](Self::new) for details about compression levels.
215 pub fn level(&self) -> u32 {
216 self.0
217 }
218 }
219
220 impl Default for Compression {
221 fn default() -> Compression {
222 Compression(6)
223 }
224 }
225
226 #[cfg(test)]
227 fn random_bytes() -> impl Iterator<Item = u8> {
228 use rand::Rng;
229 use std::iter;
230
231 iter::repeat(()).map(|_| rand::rng().random())
232 }