ZLib Compression

This page explains how to compress and decompress data using ZLib.

Code snippets assume using namespace boost::capy; is in effect.

What is ZLib?

ZLib implements the DEFLATE compression algorithm, the foundation of:

  • gzip (.gz files)

  • zlib format (with header/checksum)

  • Raw DEFLATE (no framing)

  • PNG image compression

  • HTTP compression

ZLib is universally supported and a safe choice when compatibility matters.

Setup

#include <boost/capy/zlib.hpp>
#include <boost/capy/datastore.hpp>

datastore ctx;

// Install deflate (compress) and inflate (decompress) services
auto& deflate_svc = zlib::install_deflate_service(ctx);
auto& inflate_svc = zlib::install_inflate_service(ctx);

Compression (Deflate)

std::vector<char> input = get_data();
std::vector<char> output;

// Compress with default settings
zlib::deflate_result result = deflate_svc.deflate(
    input.data(), input.size(),
    output
);

if (result.ec)
    handle_error(result.ec);

Compression Level

Level ranges from 0 (no compression) to 9 (maximum compression):

// Available levels
zlib::compression_level::none          // 0 - store only
zlib::compression_level::fast          // 1 - fastest
zlib::compression_level::default_      // 6 - balanced
zlib::compression_level::best          // 9 - smallest output

Level 6 is a good default balancing speed and ratio.

Compression Strategy

Strategies optimize for different data types:

zlib::compression_strategy::default_   // General data
zlib::compression_strategy::filtered   // Data with values near a small set
zlib::compression_strategy::huffman    // Huffman only, no string matching
zlib::compression_strategy::rle        // Run-length encoding, sequential data
zlib::compression_strategy::fixed      // Fixed Huffman codes

The default strategy works well for most data.

Decompression (Inflate)

std::vector<char> compressed = get_compressed();
std::vector<char> output;

// Decompress
zlib::inflate_result result = inflate_svc.inflate(
    compressed.data(), compressed.size(),
    output
);

if (result.ec)
    handle_error(result.ec);

Format Selection

The window bits parameter selects the format:

Window Bits Format Use Case

8-15

Raw DEFLATE

Custom framing

-8 to -15

Raw DEFLATE (negative)

Same as above

16-31 (15 + 16)

gzip

File compression, HTTP

32-47 (15 + 32)

Auto-detect

Unknown input format

gzip Format

gzip adds headers and CRC:

// Compress to gzip format
zlib::deflate_result result = deflate_svc.deflate(
    input.data(), input.size(),
    output,
    zlib::compression_level::default_,
    15 + 16  // gzip window bits
);

Auto-Detection

For decompression, auto-detect handles both gzip and zlib:

// Decompress any format
zlib::inflate_result result = inflate_svc.inflate(
    compressed.data(), compressed.size(),
    output,
    15 + 32  // auto-detect
);

Streaming

For large data that doesn’t fit in memory:

zlib::stream stream;

// Process in chunks
while (has_more_input())
{
    auto chunk = get_next_chunk();
    auto result = stream.deflate_chunk(
        chunk.data(), chunk.size(),
        output_buffer,
        zlib::flush::no_flush
    );

    // Handle partial output
    write_output(output_buffer, result.bytes_written);
}

// Finish the stream
auto result = stream.deflate_finish(output_buffer);

Flush Modes

Mode Description

zlib::flush::no_flush

Normal operation, may buffer output

zlib::flush::sync_flush

Flush all pending output

zlib::flush::full_flush

Flush and reset compression state

zlib::flush::finish

Finish the stream

Error Handling

zlib::deflate_result result = deflate_svc.deflate(input, output);

if (result.ec == zlib::error::data_error)
{
    // Input data is corrupted
}
else if (result.ec == zlib::error::buf_error)
{
    // Output buffer too small
}
else if (result.ec)
{
    std::cerr << "ZLib error: " << result.ec.message() << "\n";
}

When to Use ZLib

Use ZLib when:

  • Compatibility is important (gzip is universal)

  • Fast decompression is needed

  • Memory usage must be minimal

  • Integrating with existing gzip/zlib data

Avoid ZLib when:

  • Maximum compression ratio is needed (use Brotli)

  • Content is already compressed

Summary

Function Purpose

zlib::install_deflate_service

Create compression service

zlib::install_inflate_service

Create decompression service

deflate_svc.deflate

Compress data

inflate_svc.inflate

Decompress data

zlib::stream

Streaming compression/decompression

Next Steps

  • Brotli — Higher compression ratio

  • Containers — Service container (datastore)

Edit this Page