Debian Codegraph @

.cargo/vendor/zune-inflate/README.md

raw
1 # zune-inflate
2
3 This crate features an optimized inflate algorithm supporting
4 whole buffer decompression.
5
6 Supported formats are
7
8 - raw deflate
9 - zlib (deflate with a zlib wrapper on)
10 - gzip
11
12 The implementation is heavily based on Eric Biggers [libdeflate] and hence
13 has similar characteristics.
14
15 Specifically, we do not support streaming decompression but prefer whole buffer decompression.
16
17 ## Installation
18
19 To use in your crate, simply add the following in your
20 Cargo.toml
21
22 ```toml
23 [dependencies]
24 #other amazing crates from other amazing people
25 zune-inflate = "0.2.0"
26 ```
27
28 ## Features
29
30 One can enable or disable a specific format using
31 cargo features.
32
33 Specifically, the following can be enabled
34
35 - `gzip`: Enable decompressing of gzip encoded data
36 - `zlib`: Enable decompressing of zlib encoded data
37
38 To enable one feature, modify `Cargo.toml` entry to be
39
40 ```toml
41 [dependencies]
42 zune-inflate = { version = "0.2", default-features = false, features = ["#ADD_SPECIFIC_FEATURE"] }
43 ```
44
45 ## Usage.
46
47 The library exposes a simple API for decompressing
48 data, and depending on what type of data you have, you typically choose
49 one of the `decode[_suffix]` function to decode your data
50
51 The decompressor expects the whole buffer handed upfront
52
53 ### Decoding raw deflate
54
55 To decode raw deflate data, the following code should get you
56 started.
57
58 ```rust
59 use zune_inflate::DeflateDecoder;
60 let totally_valid_data = [0; 23];
61 let mut decoder = DeflateDecoder::new( & totally_valid_data);
62 // panic on errors, because that's the cool way to go
63 let decompressed_data = decoder.decode_deflate().unwrap();
64 ```
65
66 ### Decoding zlib
67
68 To decode deflate data wrapped in zlib, the following code should get you
69 started.
70
71 ```rust
72 use zune_inflate::DeflateDecoder;
73 let totally_valid_data = [0; 23];
74 let mut decoder = DeflateDecoder::new( & totally_valid_data);
75 // panic on errors, because that's the cool way to go
76 let decompressed_data = decoder.decode_zlib().unwrap();
77 ```
78
79 ### Advanced usage
80
81 There are advanced options specified by `DeflateOptions` which can change
82 decompression settings.
83
84 ## Comparisions.
85
86 I'll compare this with `flate2` with `miniz-oxide` backend.
87
88 | feature | `zune-inflate` | `flate2` |
89 |-------------------------|----------------|-------------------|
90 | zlib decompression | yes | yes |
91 | delfate decompression | yes | yes |
92 | gzip | yes | yes |
93 | compression | soon | yes |
94 | streaming decompression | no | yes |
95 | **unsafe** | no | yes<sup>[1]</sup> |
96
97 <sup>[1]</sup> Flate writes to an uninitialized buffer
98
99 As you can see, there are some concrete features we currently lack when compared to
100 flate2/miniz-oxide.
101
102 There's actually nothing riding in for us, except...it's wickedly fast...
103
104 ### Benchmarks
105
106 Up-to date benchmarks are done using criterion and hosted online at [zune-benchmarks] site,
107 benchmarks for this library have the `inflate: ` prefix.
108
109
110 ## Fuzzing
111
112 The decoder is currently fuzzed for correctness by both `miniz-oxide` and `zlib-ng`, see the fuzz/src directory
113
114 [libdeflater]: https://github.com/adamkewley/libdeflater
115
116 [libdeflate]:https://github.com/ebiggers/libdeflate
117
118 [criterion]:https://github.com/bheisler/criterion.rs
119
120 [zune-benchmarks]:https://etemesi254.github.io/posts/Zune-Benchmarks/