# Zlib Filters

Overview
Acknowledgments
Headers
Synopsis
Reference

namespace `boost::iostreams::zlib`
Class `zlib_params`
Class template `zlib_compressor`
Class template `zlib_decompressor`
Class `zlib_error`

Examples
Installation

## Overview

The class templates `basic_zlib_compressor` and `basic_zlib_decompressor` perform compression and decompression in the ZLIB format ([Deutsch1]) using Jean-loup Gailly's and Mark Adler's zlib compression library ([Gailly]).

The zlib Filters are DualUseFilters so that they may be used for either input or output. Most commonly, however, the compression Filters will be used for output and the decompression Filters for input.

## Acknowledgments

The zlib Filters were influences by the work of Jeff Garland ([Garland]) and Jonathan de Halleux ([de Halleux]).

Thanks to Jean-loup Gailly and Mark Adler for making their excellent library available to the public with a Boost-compatible license.

## Headers

`<boost/iostreams/filter/zlib.hpp>`

## Synopsis

    namespace boost { namespace iostreams {

    namespace zlib {

        // Compression levels

    extern const int no_compression;
    extern const int best_speed;
    extern const int best_compression;
    extern const int default_compression;

        // Compression methods

    extern const int deflated;

        // Compression strategies

    extern const int default_strategy;
    extern const int filtered;
    extern const int huffman_only;

        // Status codes

    extern const int stream_error;
    extern const int version_error;
    extern const int data_error;
    extern const int buf_error;

    }   // End namespace boost::iostreams::zlib

    struct zlib_params;

    template<typename Alloc = std::allocator<char> >
    struct basic_zlib_compressor;

    template<typename Alloc = std::allocator<char> >
    struct basic_zlib_decompressor;

    typedef basic_zlib_compressor<>   zlib_compressor;
    typedef basic_zlib_decompressor<> zlib_decompressor;

    class zlib_error;

    } } // End namespace boost::io

## Reference

### Namespace `boost::iostreams::zlib`

The namespace `boost::iostreams::zlib` contains integral constants used to configure zlib Filters and to report errors. The constants have the following interpretations. (See [Gailly] for additional details.)

Constant | Interpretation
--- | ---
`no_compression` | Compression-level constant specifying that no compression should be performed. Equal to `Z_NO_COMPRESSION`.
`best_speed` | Compression-level constant requesting the fasted compression. Equal to `Z_BEST_SPEED`.
`best_compression.` | Compression-level constant requesting the best compression ratio. Equal to `Z_BEST_COMPRESSION`.
`default_compression` | Default compression level. Equal to `Z_DEFAULT_COMPRESSION`.
`deflated` | Compression method constant; currently the only supported method. Equal to `Z_DEFLATED`.
`default_strategy` | Compression strategy constant. Equal to `Z_DEFAULT_STRATEGY`.
`filtered` | Compression strategy constant. Equal to `Z_FILTERED`.
`huffman_only` | Compression strategy constant. Equal to `Z_HUFFMAN_ONLY`.
`stream_error` | Error code used to indicate that one of the members of `zlib_params` is invalid; may also indicate an internal Iostreams library error. Equal to `Z_STREAM_ERROR`.
`version_error` | Error code used to indicate that data was compressed with an incompatible version of zlib. Equal to `Z_VERSION_ERROR`.
`data_error` | Error code used to indicate that a compressed datastream is corrupted. Equal to `Z_DATA_ERROR.`
`buf_error` | Error code indicating an internal Iostreams library error. Equal to `Z_BUF_ERROR.`

### Class `zlib_params`

#### Description

Encapsulates the parameters used to configure `basic_zlib_compressor` and `basic_zlib_decompressor`.

#### Synopsis

    struct zlib_params {

        // Non-explicit constructor
        zlib_params( int level           = zlib::default_compression,
                     int method          = zlib::deflated,
                     int window_bits     = default value,
                     int mem_level       = default value,
                     int strategy        = zlib::default_strategy,
                     bool noheader       = false );
        int  level;
        int  method;
        int  window_bits;
        int  mem_level;
        int  strategy;
        bool noheader;
    };

#### `zlib_params::zlib_params`

        zlib_params( int level           = zlib::default_compression,
                     int method          = zlib::deflated,
                     int window_bits     = default value,
                     int mem_level       = default value,
                     int strategy        = zlib::default_strategy,
                     bool noheader       = false );

Constructs a `zlib_params` object, where the parameters have the following interpretations:

level | - | Compression level. Must be equal to `zlib::default_compression` or a value in the range `0-9`. The value `0` yields no compression, while `9` yields the best compression ratio. Affects compression only.
method | - | Compression method. Must equal `zlib::deflated`. Affects compression only.
window_bits | - | The base two logarithm of the window size. Must be in the range 8-15; defaults to 15.
mem_level | - | Specifies the amount of memory to be used. Must be in the range 1-9; defaults to 8. Affects compression only.
strategy | - | Must be `zlib::default_strategy`, `zlib::filtered` or `zlib::huffman_only`. Affects compression only.
noheader | - | True if the ZLIB header and trailing ADLER-32 checksum should be omitted (see [Deutsch1]). This results in compression according to the deflate specification (see [Deutsch2]).

See [Gailly] for additional details.

### Class template `basic_zlib_compressor`

#### Description

Model of DualUseFilter which performs compression using zlib ([Gailly]).

#### Synopsis

    template<typename Alloc = std::allocator<char> >
    struct basic_zlib_compressor {
        typedef char                    char_type;
        typedef implementation-defined  category;

        basic_zlib_compressor( const zlib_params& = zlib::default_compression,
                               std::streamsize buffer_size = default value );

        // DualUseFilter members.
    };

    typedef basic_zlib_compressor<> zlib_compressor;

#### Template Parameters

Alloc | - | A C++ standard library allocator type ([ISO], 20.1.5), used to allocate a character buffer and to configure zlib.

#### `basic_zlib_compressor::basic_zlib_compressor`

        basic_zlib_compressor( const zlib_params& = zlib::default_compression,
                               std::streamsize buffer_size = default value );

Constructs an instance of `basic_zlib_compressor` with the given parameters and buffer size. Since a `zlib_params` object is implicitly constructible from an `int` representing a compression level, an `int` may be passed as the first constructor argument.

### Class template `basic_zlib_decompressor`

#### Description

Model of DualUseFilter which performs decompression using zlib ([Gailly]).

#### Synopsis

    template<typename Alloc = std::allocator<char> >
    struct basic_zlib_decompressor {
        typedef char                    char_type;
        typedef implementation-defined  category;

        basic_zlib_decompressor( int window_bits = default value,
                                 std::streamsize buffer_size =
                                     default value );
        basic_zlib_decompressor( const zlib_params&,
                                 std::streamsize buffer_size =
                                     default value );

        // DualUseFilter members.
    };

    typedef basic_zlib_decompressor<> zlib_decompressor;

#### Template Parameters

Alloc | - | A C++ standard library allocator type ([ISO], 20.1.5), used to allocate a character buffer and to configure zlib.

#### `basic_zlib_decompressor::basic_zlib_decompressor`

        basic_zlib_decompressor( int window_bits = default value,
                                 std::streamsize buffer_size =
                                     default value );
        basic_zlib_decompressor( const zlib_params&,
                                 std::streamsize buffer_size =
                                     default value );

The first member constructs an instance of `basic_zlib_decompressor` with the given parameters and buffer size. The second member constructs an instance of `basic_zlib_decompressor` with the given window bits value and buffer size. Other parameters affecting decompression are set to default values.

### Class `zlib_error`

#### Description

Used by the zlib Filters to report errors.

#### Synopsis

    class zlib_error : public std::ios_base::failure {
    public:
        zlib_error(int error);
        int error() const;
    };

#### `zlib_error::zlib_error`

        zlib_error(int error);

Constructs an instance of `zlib_error` with the given error code from the namespace `boost::iostreams::zlib`.

#### `zlib_error::error`

        void error() const;

Returns an error code from the namespace `boost::iostreams::zlib`.

## Examples

The following code decompresses data from a file and writes it to standard output.

    #include <fstream>
    #include <iostream>
    #include <boost/iostreams/filtering_streambuf.hpp>
    #include <boost/iostreams/copy.hpp>
    #include <boost/iostreams/filter/zlib.hpp>

    int main()
    {
        using namespace std;

        ifstream file("hello.z", ios_base::in | ios_base::binary);
        filtering_streambuf<input> in;
        in.push(zlib_decompressor());
        in.push(file);
        boost::iostreams::copy(in, cout);
    }

### Installation

The zlib Filters depend on the third-party zlib library, which is not included in the Boost distribution. Prebuilt zlib binaries are available on most UNIX and UNIX-like systems, and will be found automatically by the Boost build system. Windows users can obtain prebuilt binaries at the zlib homepage. Users can also configure the Boost Iostream library to build zlib from the source code, which is available at the zlib homepage. For details on configuring the build system to find your zlib installation, please see Installation.

Revised 02 Feb 2008

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)