Expand description
A DEFLATE-based stream compression/decompression library
This library provides support for compression and decompression of DEFLATE-based streams:
- the DEFLATE format itself
- the zlib format
- gzip
These three formats are all closely related and largely only differ in their headers/footers. This crate has three types in each submodule for dealing with these three formats.
§Implementation
In addition to supporting three formats, this crate supports several different backends, controlled through this crate’s features:
-
default
, orrust_backend
- this implementation uses theminiz_oxide
crate which is a port ofminiz.c
(below) to Rust. This feature does not require a C compiler and only requires Rust code. -
zlib
- this feature will enable linking against thelibz
library, typically found on most Linux systems by default. If the library isn’t found to already be on the system it will be compiled from source (this is a C library).
There’s various tradeoffs associated with each implementation, but in general you probably
won’t have to tweak the defaults. The default choice is selected to avoid the need for a C
compiler at build time. zlib-ng-compat
is useful if you’re using zlib for compatibility but
want performance via zlib-ng’s zlib-compat mode. zlib
is useful if something else in your
dependencies links the original zlib so you cannot use zlib-ng-compat. The compression ratios
and performance of each of these feature should be roughly comparable, but you’ll likely want
to run your own tests if you’re curious about the performance.
§Organization
This crate consists mainly of three modules, read
, write
, and
bufread
. Each module contains a number of types used to encode and
decode various streams of data.
All types in the write
module work on instances of Write
,
whereas all types in the read
module work on instances of
Read
and bufread
works with BufRead
. If you
are decoding directly from a &[u8]
, use the bufread
types.
use flate2::write::GzEncoder;
use flate2::Compression;
use std::io;
use std::io::prelude::*;
let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
encoder.write_all(b"Example")?;
Other various types are provided at the top-level of the crate for
management and dealing with encoders/decoders. Also note that types which
operate over a specific trait often implement the mirroring trait as well.
For example a flate2::read::DeflateDecoder<T>
also implements the
Write
trait if T: Write
. That is, the “dual trait” is forwarded directly
to the underlying object if available.
§About multi-member Gzip files
While most gzip
files one encounters will have a single member that can be read
with the GzDecoder
, there may be some files which have multiple members.
A GzDecoder
will only read the first member of gzip data, which may unexpectedly
provide partial results when a multi-member gzip file is encountered. GzDecoder
is appropriate
for data that is designed to be read as single members from a multi-member file. bufread::GzDecoder
and write::GzDecoder
also allow non-gzip data following gzip data to be handled.
The MultiGzDecoder
on the other hand will decode all members of a gzip
file
into one consecutive stream of bytes, which hides the underlying members entirely.
If a file contains contains non-gzip data after the gzip data, MultiGzDecoder will
emit an error after decoding the gzip data. This behavior matches the gzip
,
gunzip
, and zcat
command line tools.
Modules§
- Types which operate over
BufRead
streams, both encoders and decoders for various formats. - Types which operate over
Read
streams, both encoders and decoders for various formats. - Types which operate over
Write
streams, both encoders and decoders for various formats.
Structs§
- Raw in-memory compression stream for blocks of data.
- Error returned when a compression object is used incorrectly or otherwise generates an error.
- When compressing data, the compression level can be specified by a value in this struct.
- The CRC calculated by a
CrcReader
. - A wrapper around a
Read
that calculates the CRC. - A wrapper around a
Write
that calculates the CRC. - Raw in-memory decompression stream for blocks of data.
- Error returned when a decompression object finds that the input stream of bytes was not a valid input stream of bytes.
- A builder structure to create a new gzip Encoder.
- A structure representing the header of a gzip stream.
Enums§
- Values which indicate the form of flushing to be used when compressing in-memory data.
- Values which indicate the form of flushing to be used when decompressing in-memory data.
- Possible status results of compressing some data or successfully decompressing a block of data.