flate2 Rust Library

To release a new version of the flate2 crate, you must update the version in Cargo.toml, publish to crates.io, and tag the commit in Git. Note that changes cannot be made directly to main due to branch protection; all changes must go through a Pull Request.

# 1. Create a release branch
git checkout -b release-<next-version>

# 2. Update Cargo.toml with the new version
# (Manual step: edit Cargo.toml to set version = "<next-version>")

# 3. Create, approve, and merge a PR
gh pr create

# 4. Sync with main
git checkout main
git pull

# 5. Publish to crates.io
cargo publish

# 6. Tag the release
git tag <next-version>

# 7. Push tags to GitHub
git push --tags

# 8. Generate GitHub release notes via the GitHub UI

To use flate2 with its default settings (using the pure-Rust miniz_oxide backend), add it to your Cargo.toml dependencies.

[dependencies]
flate2 = "1.0"

Both GzEncoder and GzDecoder provide two ways to finalize the stream:

1. try_finish(&mut self) -> io::Result<()>: Attempts to write out final chunks (like the gzip footer or CRC). This is useful if you want to keep ownership of the encoder/decoder. Note that after calling this, further calls to write may result in a panic.
2. finish(self) -> io::Result<W>: Consumes the encoder/decoder and returns the underlying writer. This is the preferred way to re-acquire ownership of the inner stream.

Note for Async users: If you are using asynchronous I/O, finish might not be suitable; use try_finish or a shutdown method instead.

Standard GzDecoder (in read, write, or bufread modules) only decodes the first member of a gzip file. If a file contains multiple gzip members, GzDecoder may return partial results.

To decode all members of a gzip file into one continuous stream of bytes, use MultiGzDecoder. Note that MultiGzDecoder will return an error if any non-gzip data is encountered after the gzip members, matching the behavior of command-line tools like gunzip or zcat.

The flate2 crate supports multiple backends for compression and decompression. Since Cargo features are additive, if multiple backends are selected, they are activated in the following priority order:

1. zlib-ng
2. zlib-rs (typically the fastest, but uses unsafe Rust)
3. miniz_oxide (the default or rust_backend feature; uses only safe Rust and does not require a C compiler)

If you need bit-identical results to a specific C implementation, check the crate's README for available C backends.

The crate is organized into three main modules based on the type of I/O you are performing. Choose the module that matches your input/output type:

• mod bufread: Use these if you can provide a std::io::BufRead type (e.g., a &[u8] slice or a std::io::BufReader).
• mod read: Use these to wrap a std::io::Read type. Warning: These implementations may read past the end of the compressed data, making the underlying Read type unusable for subsequent reads. If you need to reuse the source, wrap it in a std::io::BufReader and use the bufread module instead.
• mod write: Use these when working with std::io::Write types, which is particularly useful when dealing with async streams/iterators where a BufRead cannot be easily created.

To decompress data, use a decoder like GzDecoder. The decoder wraps a reader containing the compressed bytes. You can then use standard std::io methods like read_to_string to extract the original content.

use std::io::prelude::*;
use flate2::read::GzDecoder;

fn main() {
    let mut d = GzDecoder::new("...".as_bytes());
    let mut s = String::new();
    d.read_to_string(&mut s).unwrap();
    println!("{}", s);
}

You can compress data by using an encoder like ZlibEncoder. The encoder wraps an underlying writer (such as a Vec<u8>) and applies compression based on a Compression level. Use .finish() to consume the encoder and retrieve the compressed data.

use std::io::prelude::*;
use flate2::Compression;
use flate2::write::ZlibEncoder;

fn main() {
    let mut e = ZlibEncoder::new(Vec::new(), Compression::default());
    e.write_all(b"foo").unwrap();
    e.write_all(b"bar").unwrap();
    let compressed_bytes = e.finish().unwrap();
}

When working with async streams, use the write module to decompress data by writing chunks from the stream into a GzDecoder.

use futures::{Stream, StreamExt};
use std::io::{Result, Write as _};

async fn decompress_gzip_stream<S, I>(stream: S) -> Result<Vec<u8>>
where
    S: Stream<Item = I>,
    I: AsRef<[u8]>
{
    let mut stream = std::pin::pin!(stream);
    let mut w = Vec::<u8>::new();
    let mut decoder = flate2::write::GzDecoder::new(w);
    while let Some(input) = stream.next().await {
        decoder.write_all(input.as_ref())?;
    }
    decoder.finish()
}

You can reuse a GzDecoder instance by calling .reset(r), which replaces the current input stream with a new one r. This clears the internal state and discards any currently buffered data. This is useful for performance when processing multiple gzip streams sequentially.

// Example of resetting a decoder
let mut decoder = GzDecoder::new(compressed_data_1);
// ... read data ...

// Reset with a new stream
decoder.reset(compressed_data_2);
// ... read new data ...

If you need to reuse a DeflateEncoder with a different output stream, use the reset(w: W) method.

This method will first finish encoding the current stream into the existing output stream. Once finished, it resets the internal state and replaces the current output stream with the provided stream w, returning the old stream. This is useful for avoiding re-allocations or managing multiple output targets.

// Example concept for reset
// e.reset(new_writer)? returns the old_writer