Gzip Filters

OverviewAcknowledgmentsHeadersSynopsisReferencenamespace boost::iostreams::gzipClass gzip_paramsClass template gzip_compressorClass template gzip_decompressorClass gzip_errorExamplesInstallation

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

namespaceboost {namespaceiostreams {namespace[gzip](#constants){usingnamespace[boost::iostreams::zlib](zlib.html#constants);// Error codes used by gzip\_error.constint[zlib\_error](#zlib_error);constint[bad\_crc](#bad_crc);constint[bad\_length](#bad_length);constint[bad\_header](#bad_header);constint[bad\_footer](#bad_footer);

}// End namespace boost::iostreams::gzipstruct[gzip\_params](#gzip_params);template<typenameAlloc = std::allocator<char> >struct[basic\_gzip\_compressor](#basic_gzip_compressor);template<typenameAlloc = std::allocator<char> >struct[basic\_gzip\_decompressor](#basic_gzip_decompressor);typedefbasic_gzip_compressor<>gzip\_compressor;typedefbasic_gzip_decompressor<>gzip\_decompressor;class[gzip\_error](#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.)

Class gzip_params

Description

Encapsulates the parameters used to configure basic_gzip_compressor and basic_gzip_decompressor.

Synopsis

structgzip\_params:[zlib\_params](zlib.html#zlib_params){// Non-explicit constructor.[gzip\_params](#gzip_params_constructor)(intlevel =default value,intmethod =default value,intwindow_bits =default value,intmem_level =default value,intstrategy =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(intlevel =default value,intmethod =default value,intwindow_bits =default value,intmem_level =default value,intstrategy =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](#basic_gzip_compressor_params)= std::allocator<char> >struct[basic\_gzip\_compressor](#basic_gzip_compressor_params){typedefcharchar_type;typedefimplementation-definedcategory;[basic\_gzip\_compressor](#basic_gzip_compressor_ctors)(const[gzip\_params](#gzip_params)& =zlib::default\_compression,
                           std::streamsize buffer_size =default value);// DualUseFilter members.};typedefbasic_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(constgzip_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 DualUseFilter which decompresses data in the GZIP format ([Deutsch3]).

Synopsis

template<typename[Alloc](#basic_gzip_decompressor_params)= std::allocator<char> >struct[basic\_gzip\_decompressor](#basic_gzip_decompressor_params){typedefcharchar_type;typedefimplementation-definedcategory;[basic\_gzip\_decompressor](#basic_gzip_decompressor_constructor)(intwindow_bits =default value, 
                             std::streamsize buffer_size =default value);// DualUseFilter members.};typedefbasic_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(intwindow_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

classgzip\_error:publicstd::ios_base::failure {public:[gzip\_error](#gzip_error_constructor)(interror);[gzip\_error](#gzip_error_constructor)(const[zlib\_error](zlib.html#zlib_error)& e);int[error](#gzip_error_error)()const;int[zlib\_error\_code](#gzip_error_zlib_error_code)()const;
};

gzip_error::gzip_error

gzip_error(interror);
    gzip_error(const[zlib\_error](#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

voiderror()const;

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

voidzlib_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\>](../../../../boost/iostreams/filtering_streambuf.hpp)#include[\<boost/iostreams/copy.hpp\>](../../../../boost/iostreams/copy.hpp)#include[\<boost/iostreams/filter/gzip.hpp\>](../../../../boost/iostreams/filter/gzip.hpp)int main() 
{usingnamespacestd;

    ifstream file("hello.gz", ios_base::in | ios_base::binary);
    boost::iostreams::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.

© 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)