Debian Codegraph @

.cargo/vendor/flate2/README.md

raw
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
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.