Bzip2 Filters

OverviewAcknowledgmentsHeadersSynopsisReferencenamespace boost::iostreams::bzip2Class bzip2_paramsClass template bzip2_compressorClass template bzip2_decompressorClass bzip2_errorExamplesInstallation

Overview

The class templates basic_bzip2_compressor and basic_bzip2_decompressor perform compression and decompression using Julian Seward's libbzip2 compression library ([Seward]).

The bzip2 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 bzip2 Filters were influences by the work of Jeff Garland ([Garland]) and Jonathan de Halleux ([de Halleux]).

Thanks to Julian Seward for making his excellent library available to the public with a Boost-compatible license.

Headers

<boost/iostreams/filter/bzip2.hpp>

Synopsis

namespaceboost {namespaceiostreams {namespace[bzip2](#constants){// Error codesexternconstint[data\_error](#data_error);externconstint[data\_error\_magic](#data_error_magic);externconstint[config\_error](#config_error);

}// End namespace boost::iostreams::bzip2struct[bzip2\_params](#bzip2_params);template<typenameAlloc = std::allocator<char> >struct[basic\_bzip2\_compressor](#basic_bzip2_compressor);template<typenameAlloc = std::allocator<char> >struct[basic\_bzip2\_decompressor](#basic_bzip2_decompressor);typedefbasic_bzip2_compressor<>bzip2\_compressor;typedefbasic_bzip2_decompressor<>bzip2\_decompressor;class[bzip2\_error](#bzip2_error);

} }// End namespace boost::io

Reference

Namespace boost::iostreams::bzip2

The namespace boost::iostreams::bzip2 contains integral error codes. The constants have the following interpretations. See [Seward] for additional details.

Class bzip2_params

Description

Encapsulates the parameters used to configure basic_bzip2_compressor and basic_bzip2_decompressor.

Synopsis

structbzip2\_params{// Non-explicit constructor for compression[bzip2\_params](#bzip2_params_constructors)(intblock_size =default value,intwork_factor =default value);// Constructor for decompression.[bzip2\_params](#bzip2_params_constructors)(boolsmall );union{int[block\_size](#block_size);// For compressionbool[small](#small);// For decompression};int[work\_factor](#work_factor);// For compression};

bzip2_params::bzip2_params

bzip2_params(intblock_size =default value,intwork_factor =default value);
    bzip2_params(boolsmall );

The first member constructs a bzip2_params object for configuring basic_bzip2_compressor.

| | | | block_size | - | Block size to use for compression; actual block size is 100000 * block_size. Must be in range 1-9. | | work_factor | - | Controls behavior of compression with worst case data. Must be in the range 0-250. |

The second constructs a bzip2_params object for configuring basic_bzip2_decompressor.

| | | | small | - | Indicates whether a slower decompression algorithm, using less memory, should be used. |

See [Seward] for additional details.

Class template basic_bzip2_compressor

Description

Model of DualUseFilter which performs compression using libbzip2 ([Seward]).

Synopsis

template<typename[Alloc](#basic_bzip2_compressor_params)= std::allocator<char> >struct[basic\_bzip2\_compressor](#basic_bzip2_compressor_params){typedefcharchar_type;typedefimplementation-definedcategory;[basic\_bzip2\_compressor](#basic_bzip2_compressor_constructors)(const[bzip2\_params](#bzip2_params)& =bzip2::default\_block\_size,
                            std::streamsize buffer_size =default value);...};typedefbasic_bzip2_compressor<>bzip2\_compressor;

Template Parameters

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

basic_bzip2_compressor::basic_bzip2_compressor

basic_bzip2_compressor(const[bzip2\_params](#bzip2_params)&, std::streamsize buffer_size);

Constructs an instance of basic_bzip2_compressor with the given parameters and buffer size. Since a bzip2_params object is implicitly constructible from an int representing a block size, an int may be passed as the first constructor argument.

Class template basic_bzip2_decompressor

Description

Model of DualUseFilter which performs decompression using libbzip2 ([Seward]).

Synopsis

template<typename[Alloc](#basic_bzip2_decompressor_params)= std::allocator<char> >struct[basic\_bzip2\_decompressor](#basic_bzip2_decompressor_params){typedefcharchar_type;typedefimplementation-definedcategory;[basic\_bzip2\_decompressor](#basic_bzip2_decompressor_constructors)(boolsmall =false, 
                              std::streamsize buffer_size =default value);...};typedefbasic_bzip2_decompressor<>bzip2\_decompressor;

Template Parameters

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

basic_bzip2_decompressor::basic_bzip2_decompressor

basic_bzip2_decompressor(boolsmall, std::streamsize buffer_size);

Constructs an instance of basic_bzip2_decompressor with the given value for small and the given buffer size.

Class bzip2_error

Description

Used by the bzip2 Filters to report errors.

Synopsis

classbzip2\_error:publicstd::ios_base::failure {public:[bzip2\_error](#bzip2_error_constructor)(interror);int[error](#bzip2_error_error)() const;
};

bzip2_error::bzip2_error

bzip2_error(interror);

Constructs an instance of bzip2_error with the given error code from the namespace boost::iostreams::bzip2.

bzip2_error::error

voiderror()const;

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

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/bzip2.hpp\>](../../../../boost/iostreams/filter/bzip2.hpp)int main() 
{usingnamespacestd;usingnamespaceboost::iostreams;

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

Installation

The bzip2 Filters depend on the third-party libbz2 library, which is not included in the Boost distribution. Prebuilt libbz2 binaries are available on most UNIX and UNIX-like systems, and will be found automatically by the Boost build system. Users can also configure the Boost Iostream library to build libbz2 from the source code, which is available at the libbz2 homepage. For details on configuring the build system to find your libbz2 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)