1# flate2
2
3[![Crates.io](https://img.shields.io/crates/v/flate2.svg?maxAge=2592000)](https://crates.io/crates/flate2)
4[![Documentation](https://docs.rs/flate2/badge.svg)](https://docs.rs/flate2)
5
6A streaming compression/decompression library DEFLATE-based streams in Rust.
7
8This crate by default uses the `miniz_oxide` crate, a port of `miniz.c` to pure
9Rust. This crate also supports other [backends](#backends), such as the widely
10available zlib library or the high-performance zlib-ng library.
11
12Supported formats:
13
14* deflate
15* zlib
16* gzip
17
18```toml
19# Cargo.toml
20[dependencies]
21flate2 = "1.0"
22```
23
24## MSRV (Minimum Supported Rust Version) Policy
25
26This crate supports the current stable and the last stable for the latest version.
27For example, if the current stable is 1.64, this crate supports 1.64 and 1.63.
28Older stables may work, but we don't guarantee these will continue to work.
29
30## Compression
31
32```rust
33use std::io::prelude::*;
34use flate2::Compression;
35use flate2::write::ZlibEncoder;
36
37fn main() {
38    let mut e = ZlibEncoder::new(Vec::new(), Compression::default());
39    e.write_all(b"foo");
40    e.write_all(b"bar");
41    let compressed_bytes = e.finish();
42}
43```
44
45## Decompression
46
47```rust,no_run
48use std::io::prelude::*;
49use flate2::read::GzDecoder;
50
51fn main() {
52    let mut d = GzDecoder::new("...".as_bytes());
53    let mut s = String::new();
54    d.read_to_string(&mut s).unwrap();
55    println!("{}", s);
56}
57```
58
59## Backends
60
61The default `miniz_oxide` backend has the advantage of being pure Rust. If you
62want maximum performance, you can use the zlib-ng C library:
63
64```toml
65[dependencies]
66flate2 = { version = "1.0.17", features = ["zlib-ng"], default-features = false }
67```
68
69Note that the `"zlib-ng"` feature works even if some other part of your crate
70graph depends on zlib.
71
72However, if you're already using another C or Rust library that depends on
73zlib, and you want to avoid including both zlib and zlib-ng, you can use that
74for Rust code as well:
75
76```toml
77[dependencies]
78flate2 = { version = "1.0.17", features = ["zlib"], default-features = false }
79```
80
81Or, if you have C or Rust code that depends on zlib and you want to use zlib-ng
82via libz-sys in zlib-compat mode, use:
83
84```toml
85[dependencies]
86flate2 = { version = "1.0.17", features = ["zlib-ng-compat"], default-features = false }
87```
88
89Note that when using the `"zlib-ng-compat"` feature, if any crate in your
90dependency graph explicitly requests stock zlib, or uses libz-sys directly
91without `default-features = false`, you'll get stock zlib rather than zlib-ng.
92See [the libz-sys
93README](https://github.com/rust-lang/libz-sys/blob/main/README.md) for details.
94To avoid that, use the `"zlib-ng"` feature instead.
95
96For compatibility with previous versions of `flate2`, the Cloudflare optimized
97version of zlib is available, via the `cloudflare_zlib` feature. It's not as
98fast as zlib-ng, but it's faster than stock zlib. It requires an x86-64 CPU with
99SSE 4.2 or ARM64 with NEON & CRC. It does not support 32-bit CPUs at all and is
100incompatible with mingw. For more information check the [crate
101documentation](https://crates.io/crates/cloudflare-zlib-sys). Note that
102`cloudflare_zlib` will cause breakage if any other crate in your crate graph
103uses another version of zlib/libz.
104
105# License
106
107This project is licensed under either of
108
109 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
110   https://www.apache.org/licenses/LICENSE-2.0)
111 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
112   https://opensource.org/licenses/MIT)
113
114at your option.
115
116### Contribution
117
118Unless you explicitly state otherwise, any contribution intentionally submitted
119for inclusion in this project by you, as defined in the Apache-2.0 license,
120shall be dual licensed as above, without any additional terms or conditions.
121