Bzip2 Filters

Overview
Acknowledgments
Headers
Synopsis
Reference
namespace boost::iostreams::bzip2
Class bzip2_params
Class template bzip2_compressor
Class template bzip2_decompressor
Class bzip2_error
Examples
Installation

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

namespace boost { namespace iostreams {

namespace bzip2 {
                    
    // Error codes

extern const int data_error;
extern const int data_error_magic;
extern const int config_error;

}   // End namespace boost::iostreams::bzip2

struct bzip2_params;

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

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

typedef basic_bzip2_compressor<>   bzip2_compressor;
typedef basic_bzip2_decompressor<> bzip2_decompressor;

class 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.

ConstantInterpretation
data_error Indicates that the compressed data stream is corrupted. Equal to BZ_DATA_ERROR.
data_error_magic Indicates that the compressed data stream does not begin with the 'magic' sequence 'B' 'Z' 'h'. Equal to BZ_DATA_ERROR_MAGIC.
config_error Indicates that libbzip2 has been improperly configured for the current platform. Equal to BZ_CONFIG_ERROR.

Class bzip2_params

Description

Encapsulates the parameters used to configure basic_bzip2_compressor and basic_bzip2_decompressor.

Synopsis

struct bzip2_params {

    // Non-explicit constructor for compression
    bzip2_params( int block_size   = default value,
                  int work_factor  = default value );

    // Constructor for decompression.
    bzip2_params( bool small );

    union {
        int   block_size;    // For compression
        bool  small;         // For decompression
    };
    int       work_factor;   // For compression
};

bzip2_params::bzip2_params

    bzip2_params( int block_size   = default value,
                  int work_factor  = default value );
    bzip2_params( bool small );

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 = std::allocator<char> >
struct basic_bzip2_compressor {
    typedef char                    char_type;
    typedef implementation-defined  category;

    basic_bzip2_compressor( const bzip2_params& = bzip2::default_block_size, 
                            std::streamsize buffer_size = default value );
    ...
};

typedef basic_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&, 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 = std::allocator<char> >
struct basic_bzip2_decompressor {
    typedef char                    char_type;
    typedef implementation-defined  category;

    basic_bzip2_decompressor( bool small = false, 
                              std::streamsize buffer_size = 
                                  default value );
    ...
};

typedef basic_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(bool small, 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

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

bzip2_error::bzip2_error

    bzip2_error(int error);

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

bzip2_error::error

    void error() 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>
#include <boost/iostreams/copy.hpp>
#include <boost/iostreams/filter/bzip2.hpp>

int main() 
{
    using namespace std;
    using namespace boost::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.