| 1 |
# flate2 |
| 2 |
|
| 3 |
[](https://crates.io/crates/flate2) |
| 4 |
[](https://docs.rs/flate2) |
| 5 |
|
| 6 |
A streaming compression/decompression library DEFLATE-based streams in Rust. |
| 7 |
|
| 8 |
This crate by default uses the `miniz_oxide` crate, a port of `miniz.c` to pure |
| 9 |
Rust. This crate also supports other [backends](#backends), such as the widely |
| 10 |
available zlib library or the high-performance zlib-ng library. |
| 11 |
|
| 12 |
Supported formats: |
| 13 |
|
| 14 |
* deflate |
| 15 |
* zlib |
| 16 |
* gzip |
| 17 |
|
| 18 |
```toml |
| 19 |
# Cargo.toml |
| 20 |
[dependencies] |
| 21 |
flate2 = "1.0" |
| 22 |
``` |
| 23 |
|
| 24 |
## MSRV (Minimum Supported Rust Version) Policy |
| 25 |
|
| 26 |
This crate supports the current and previous stable versions of the Rust compiler. |
| 27 |
For example, if the current stable is 1.80, this crate supports 1.80 and 1.79. |
| 28 |
|
| 29 |
Other compiler versions may work, but failures may not be treated as a `flate2` bug. |
| 30 |
|
| 31 |
The `Cargo.toml` file specifies a `rust-version` for which builds of the current version |
| 32 |
passed at some point. This value is indicative only, and may change at any time. |
| 33 |
|
| 34 |
The `rust-version` is a best-effort measured value and is different to the MSRV. The |
| 35 |
`rust-version` can be incremented by a PR in order to pass tests, as long as the MSRV |
| 36 |
continues to hold. When the `rust-version` increases, the next release should be a minor |
| 37 |
version, to allow any affected users to pin to a previous minor version. |
| 38 |
|
| 39 |
## Compression |
| 40 |
|
| 41 |
```rust |
| 42 |
use std::io::prelude::*; |
| 43 |
use flate2::Compression; |
| 44 |
use flate2::write::ZlibEncoder; |
| 45 |
|
| 46 |
fn main() { |
| 47 |
let mut e = ZlibEncoder::new(Vec::new(), Compression::default()); |
| 48 |
e.write_all(b"foo"); |
| 49 |
e.write_all(b"bar"); |
| 50 |
let compressed_bytes = e.finish(); |
| 51 |
} |
| 52 |
``` |
| 53 |
|
| 54 |
## Decompression |
| 55 |
|
| 56 |
```rust,no_run |
| 57 |
use std::io::prelude::*; |
| 58 |
use flate2::read::GzDecoder; |
| 59 |
|
| 60 |
fn main() { |
| 61 |
let mut d = GzDecoder::new("...".as_bytes()); |
| 62 |
let mut s = String::new(); |
| 63 |
d.read_to_string(&mut s).unwrap(); |
| 64 |
println!("{}", s); |
| 65 |
} |
| 66 |
``` |
| 67 |
|
| 68 |
## Backends |
| 69 |
|
| 70 |
The default `miniz_oxide` backend has the advantage of only using safe Rust. |
| 71 |
|
| 72 |
If you want maximum performance while still benefiting from a Rust |
| 73 |
implementation at the cost of some `unsafe`, you can use `zlib-rs`: |
| 74 |
|
| 75 |
```toml |
| 76 |
[dependencies] |
| 77 |
flate2 = { version = "1.0.17", features = ["zlib-rs"], default-features = false } |
| 78 |
``` |
| 79 |
|
| 80 |
### C backends |
| 81 |
|
| 82 |
While zlib-rs is [the fastest overall](https://trifectatech.org/blog/zlib-rs-is-faster-than-c/), |
| 83 |
the zlib-ng C library can be slightly faster in certain cases: |
| 84 |
|
| 85 |
```toml |
| 86 |
[dependencies] |
| 87 |
flate2 = { version = "1.0.17", features = ["zlib-ng"], default-features = false } |
| 88 |
``` |
| 89 |
|
| 90 |
Note that the `"zlib-ng"` feature works even if some other part of your crate |
| 91 |
graph depends on zlib. |
| 92 |
|
| 93 |
However, if you're already using another C or Rust library that depends on |
| 94 |
zlib, and you want to avoid including both zlib and zlib-ng, you can use that |
| 95 |
for Rust code as well: |
| 96 |
|
| 97 |
```toml |
| 98 |
[dependencies] |
| 99 |
flate2 = { version = "1.0.17", features = ["zlib"], default-features = false } |
| 100 |
``` |
| 101 |
|
| 102 |
Or, if you have C or Rust code that depends on zlib and you want to use zlib-ng |
| 103 |
via libz-sys in zlib-compat mode, use: |
| 104 |
|
| 105 |
```toml |
| 106 |
[dependencies] |
| 107 |
flate2 = { version = "1.0.17", features = ["zlib-ng-compat"], default-features = false } |
| 108 |
``` |
| 109 |
|
| 110 |
Note that when using the `"zlib-ng-compat"` feature, if any crate in your |
| 111 |
dependency graph explicitly requests stock zlib, or uses libz-sys directly |
| 112 |
without `default-features = false`, you'll get stock zlib rather than zlib-ng. |
| 113 |
See [the libz-sys |
| 114 |
README](https://github.com/rust-lang/libz-sys/blob/main/README.md) for details. |
| 115 |
To avoid that, use the `"zlib-ng"` feature instead. |
| 116 |
|
| 117 |
For compatibility with previous versions of `flate2`, the Cloudflare optimized |
| 118 |
version of zlib is available, via the `cloudflare_zlib` feature. It's not as |
| 119 |
fast as zlib-ng, but it's faster than stock zlib. It requires an x86-64 CPU with |
| 120 |
SSE 4.2 or ARM64 with NEON & CRC. It does not support 32-bit CPUs at all and is |
| 121 |
incompatible with mingw. For more information check the [crate |
| 122 |
documentation](https://crates.io/crates/cloudflare-zlib-sys). Note that |
| 123 |
`cloudflare_zlib` will cause breakage if any other crate in your crate graph |
| 124 |
uses another version of zlib/libz. |
| 125 |
|
| 126 |
# License |
| 127 |
|
| 128 |
This project is licensed under either of |
| 129 |
|
| 130 |
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or |
| 131 |
https://www.apache.org/licenses/LICENSE-2.0) |
| 132 |
* MIT license ([LICENSE-MIT](LICENSE-MIT) or |
| 133 |
https://opensource.org/licenses/MIT) |
| 134 |
|
| 135 |
at your option. |
| 136 |
|
| 137 |
### Contribution |
| 138 |
|
| 139 |
Unless you explicitly state otherwise, any contribution intentionally submitted |
| 140 |
for inclusion in this project by you, as defined in the Apache-2.0 license, |
| 141 |
shall be dual licensed as above, without any additional terms or conditions. |