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

Constant | Interpretation
--- | ---
`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.

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)