Crate flate2

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 three different backends, controlled through this crate’s features:

• default, or rust_backend - this implementation uses the miniz_oxide crate which is a port of miniz.c (below) to Rust. This feature does not require a C compiler and only requires Rust code.

• miniz-sys - when enabled this feature will enable this crate to instead use miniz.c, distributed with miniz-sys, to implement compression/decompression.

• zlib - finally, this feature will enable linking against the libz 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. The miniz-sys feature is largely a historical artifact at this point and is unlikely to be needed, and zlib is often useful if you’re already using zlib for other C dependencies. 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.

Async I/O

This crate optionally can support async I/O streams with the Tokio stack via the tokio feature of this crate:

flate2 = { version = "0.2", features = ["tokio"] }

All methods are internally capable of working with streams that may return ErrorKind::WouldBlock when they’re not ready to perform the particular operation.

Note that care needs to be taken when using these objects, however. The Tokio runtime, in particular, requires that data is fully flushed before dropping streams. For compatibility with blocking streams all streams are flushed/written when they are dropped, and this is not always a suitable time to perform I/O. If I/O streams are flushed before drop, however, then these operations will be a noop.

Modules

• bufread
  Types which operate over BufRead streams, both encoders and decoders for various formats.
• read
  Types which operate over Read streams, both encoders and decoders for various formats.
• write
  Types which operate over Write streams, both encoders and decoders for various formats.

Structs

• Compress
  Raw in-memory compression stream for blocks of data.
• CompressError
  Error returned when a compression object is used incorrectly or otherwise generates an error.
• Compression
  When compressing data, the compression level can be specified by a value in this enum.
• Crc
  The CRC calculated by a CrcReader.
• CrcReader
  A wrapper around a Read that calculates the CRC.
• CrcWriter
  A wrapper around a Write that calculates the CRC.
• Decompress
  Raw in-memory decompression stream for blocks of data.
• DecompressError
  Error returned when a decompression object finds that the input stream of bytes was not a valid input stream of bytes.
• GzBuilder
  A builder structure to create a new gzip Encoder.
• GzHeader
  A structure representing the header of a gzip stream.

Enums

• FlushCompress
  Values which indicate the form of flushing to be used when compressing in-memory data.
• FlushDecompress
  Values which indicate the form of flushing to be used when decompressing in-memory data.
• Status
  Possible status results of compressing some data or successfully decompressing a block of data.