A DEFLATE-based stream compression/decompression library

This library provides support for compression and decompression ofDEFLATE-based streams:

• the DEFLATE format itself
• the zlib format
• gzip

These three formats are all closely related and largely only differ in theirheaders/footers. This crate has three types in each submodule for dealingwith these three formats.

§Implementation

In addition to supporting three formats, this crate supports several differentbackends, controlled through this crate’s features:

• default, orrust_backend - this implementation uses theminiz_oxidecrate which is a port ofminiz.c to Rust. This feature does notrequire a C compiler, and only uses safe Rust code.

• zlib-rs - this implementation utilizes thezlib-rs crate, a Rust rewrite of zlib.This backend is the fastest, at the cost of someunsafe Rust code.

Several backends implemented in C are also available.These are useful in case you are already using a specific C implementationand need the result of compression to be bit-identical.See the crate’s README for details on the available C backends.

Thezlib-rs backend typically outperforms all the C implementations.

§Organization

This crate consists mainly of three modules,read,write, andbufread. Each module contains a number of types used to encode anddecode various streams of data.

All types in thewrite module work on instances ofWrite,whereas all types in theread module work on instances ofRead andbufread works withBufRead. If youare decoding directly from a&[u8], use thebufread types.

useflate2::write::GzEncoder;useflate2::Compression;usestd::io;usestd::io::prelude::*;letmutencoder = GzEncoder::new(Vec::new(), Compression::default());encoder.write_all(b"Example")?;

Other various types are provided at the top-level of the crate formanagement and dealing with encoders/decoders. Also note that types whichoperate over a specific trait often implement the mirroring trait as well.For example aflate2::read::DeflateDecoder<T>also implements theWrite trait ifT: Write. That is, the “dual trait” is forwarded directlyto the underlying object if available.

§About multi-member Gzip files

While mostgzip files one encounters will have a singlemember that can be readwith theGzDecoder, there may be some files which have multiple members.

AGzDecoder will only read the first member of gzip data, which may unexpectedlyprovide partial results when a multi-member gzip file is encountered.GzDecoder is appropriatefor data that is designed to be read as single members from a multi-member file.bufread::GzDecoderandwrite::GzDecoder also allow non-gzip data following gzip data to be handled.

TheMultiGzDecoder on the other hand will decode all members of agzip fileinto one consecutive stream of bytes, which hides the underlyingmembers entirely.If a file contains non-gzip data after the gzip data, MultiGzDecoder willemit an error after decoding the gzip data. This behavior matches thegzip,gunzip, andzcat command line tools.