# Gzip Filters

Overview
Acknowledgments
Headers
Synopsis
Reference

namespace `boost::iostreams::gzip`
Class `gzip_params`
Class template `gzip_compressor`
Class template `gzip_decompressor`
Class `gzip_error`

Examples
Installation

## Overview

The class templates `basic_gzip_compressor` and `basic_gzip_decompressor` perform compression and decompression based on the GZIP format ([Deutsch3]) using Jean-loup Gailly's and Mark Adler's zlib compression library ([Gailly]). They are implementation as derived classes of the Zlib Filters. The difference between the GZIP and ZLIB formats is that data in the GZIP contains more header information and a different checksum ([Deutsch1], [Deutsch3]).

Currently, `basic_gzip_compressor` is a DualUseFilters, but `basic_gzip_compressor` is only an InputFilter.

## Acknowledgments

The gzip 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/gzip.hpp>`

## Synopsis

    namespace boost { namespace iostreams {

    namespace gzip {

    using namespace boost::iostreams::zlib;

        // Error codes used by gzip_error.

    const int zlib_error;
    const int bad_crc;
    const int bad_length;
    const int bad_header;
    const int bad_footer;

    }   // End namespace boost::iostreams::gzip

    struct gzip_params;

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

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

    typedef basic_gzip_compressor<>   gzip_compressor;
    typedef basic_gzip_decompressor<> gzip_decompressor;

    class gzip_error;

    } } // End namespace boost::io

## Reference

### Namespace `boost::iostreams::gzip`

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

Constant | Interpretation
--- | ---
`zlib_error` | A zlib error has occured; use `gzip_error::zlib_error_code` to obtain an error code.
`bad_crc` | Recorded crc doesn't match data.
`bad_length` | Recorded length doesn't match data.
`bad_header` | Malformed file header.
`bad_footer` | Portion of file following compressed data is malformed.

### Class `gzip_params`

#### Description

Encapsulates the parameters used to configure `basic_gzip_compressor` and `basic_gzip_decompressor`.

#### Synopsis

    struct gzip_params : zlib_params {

        // Non-explicit constructor.
        gzip_params( int level              = default value,
                     int method             = default value,
                     int window_bits        = default value,
                     int mem_level          = default value,
                     int strategy           = default value,
                     std::string file_name  = "",
                     std::string comment    = "",
                     std::time_t mtime      = 0 );

        std::string  file_name;
        std::string  comment;
        std::time_t  mtime;
    };

#### `gzip_params::gzip_params`

        gzip_params( int level              = default value,
                     int method             = default value,
                     int window_bits        = default value,
                     int mem_level          = default value,
                     int strategy           = default value,
                     std::string file_name  = "",
                     std::string comment    = "",
                     std::time_t mtime      = 0 );

Constructs a `gzip_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.
file_name | - | Represents the optional section of the GZIP header containing a file name.
comment | - | Represents the optional section of the GZIP header containing a comment.
mtime | - | Represents the optional section of the GZIP header containing a file modification time.

See [Gailly] and [Deutsch1] for additional details.

### Class template `basic_gzip_compressor`

#### Description

Model of DualUseFilter which compresses data in the GZIP format ([Deutsch3]).

#### Synopsis

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

        basic_gzip_compressor( const gzip_params& = zlib::default_compression,
                               std::streamsize buffer_size = default value );

        // DualUseFilter members.
    };

    typedef basic_gzip_compressor<> gzip_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_gzip_compressor::basic_gzip_compressor`

        basic_gzip_compressor( const gzip_params& = zlib::default_compression,
                               std::streamsize buffer_size = default value );

Constructs an instance of `basic_gzip_compressor` with the given parameters and buffer size. Since a `gzip_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_gzip_decompressor`

#### Description

Model of InputFilter which decompresses data in the GZIP format ([Deutsch3]).

#### Synopsis

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

        basic_gzip_decompressor( int window_bits = default value,
                                 std::streamsize buffer_size =
                                     default value );

        // DualUseFilter members.
    };

    typedef basic_gzip_decompressor<> gzip_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_gzip_decompressor::basic_gzip_decompressor`

        basic_gzip_decompressor( int window_bits = default value,
                                 std::streamsize buffer_size =
                                     default value );

Constructs an instance of `basic_gzip_decompressor` with the given window bits value and buffer size. Other parameters affecting decompression are set to default values.

### Class `gzip_error`

#### Description

Used by the gzip Filters to report errors.

#### Synopsis

    class gzip_error : public std::ios_base::failure {
    public:
        gzip_error(int error);
        gzip_error(const zlib_error& e);
        int error() const;
        int zlib_error_code() const;
    };

#### `gzip_error::gzip_error`

        gzip_error(int error);
        gzip_error(const zlib_error& e);

The first member constructs an instance of `gzip_error` with the given error code from the namespace `boost::iostreams::gzip`. The second constructs an instance of `gzip_error` based on an instance of `zlib_error`.

#### `gzip_error::error`

        void error() const;

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

        void zlib_error_code() const;

Returns an error code from the namespace `boost::iostreams::zlib`. Meaningful only if `error()` returns the constant `boost::iostreams::gzip::zlib_error`.

## 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/gzip.hpp>

    int main()
    {
        using namespace std;

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

### Installation

The gzip 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)