Crate flate2

Source
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, or rust_backend - this implementation uses the miniz_oxide crate which is a port of miniz.c to Rust. This feature does not require a C compiler, and only uses safe Rust code.

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

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

The zlib-rs backend typically outperforms all the C implementations.

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

  • bufread
    Types which operate over BufRead streams, both encoders and decoders for various formats.
  • bufreader 🔒
  • crc 🔒
    Simple CRC bindings backed by miniz.c
  • deflate 🔒
  • ffi 🔒
    This module contains backend-specific code.
  • gz 🔒
  • mem 🔒
  • 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.
  • zio 🔒
  • zlib 🔒

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 struct.
  • 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.

Functions§