Crate flate2

A DEFLATE-based stream compression/decompression library

This library is meant to supplement/replace the standard distributon’s libflate library by providing a streaming encoder/decoder rather than purely an in-memory encoder/decoder.

Like with libflate, flate2 is based on miniz.c

Organization

This crate consists mainly of two modules, read and write. 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.

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(b"Example")?;

Other various types are provided at the top-level of the crate for management and dealing with encoders/decoders.

Helper traits

There are two helper traits provided: FlateReadExt and FlateWriteExt. These provide convenience methods for creating a decoder/encoder out of an already existing stream to chain construction.

use flate2::{FlateReadExt, Compression};
use std::io::prelude::*;
use std::io;
use std::fs::File;

// Read contents of file with a compression stream, then decompress with GZ

let f = File::open("examples/hello_world.txt")?;

//gz_encode method comes from FlateReadExt and applies to a std::fs::File
let data = f.gz_encode(Compression::Default);
let mut buffer = String::new();

//gz_decode method comes from FlateReadExt and applies to a &[u8]
&data.gz_decode()?.read_to_string(&mut buffer)?;

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.
• Crc
  The CRC calculated by a CrcReader.
• CrcReader
  A wrapper around a Read that calculates the CRC.
• DataError
  Error returned when a decompression object finds that the input stream of bytes was not a valid input stream of bytes.
• Decompress
  Raw in-memory decompression stream for blocks of data.
• GzBuilder
  A builder structure to create a new gzip Encoder.
• GzHeader
  A structure representing the header of a gzip stream.

Enums

• Compression
  When compressing data, the compression level can be specified by a value in this enum.
• Flush
  Values which indicate the form of flushing to be used when compressing or decompressing in-memory data.
• Status
  Possible status results of compressing some data or successfully decompressing a block of data.

Traits

• FlateReadExt
  A helper trait to create encoder/decoders with method syntax.
• FlateWriteExt
  A helper trait to create encoder/decoders with method syntax.