| 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/ |