Files
iostreams/doc/classes/bzip2.html
Jonathan Turkanis b85cc3c126 fixed broken link
[SVN r27130]
2005-02-05 01:59:51 +00:00

328 lines
17 KiB
HTML
Executable File

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Bzip2 Filters</TITLE>
<LINK REL='stylesheet' HREF='../../../../boost.css'>
<LINK REL='stylesheet' HREF='../theme/iostreams.css'>
</HEAD>
<BODY>
<!-- Begin Banner -->
<H1 CLASS='title'>Bzip2 Filters</H1>
<HR CLASS='banner'>
<!-- End Banner -->
<DL class='page-index'>
<DT><A href='#overview'>Overview</A></DT>
<DT><A href='#acknowledgments'>Acknowledgments</A></DT>
<DT><A href='#headers'>Headers</A></DT>
<DT><A href='#synopsis'>Synopsis</A></DT>
<DT><A HREF='#reference'>Reference</A>
<DL class='page-index'>
<DT><A HREF='#constants'>namespace <CODE>boost::iostreams::bzip2</CODE></A></DT>
<DT><A HREF='#bzip2_params'>Class <CODE>bzip2_params</CODE></A></DT>
<DT><A HREF='#basic_bzip2_compressor'>Class template <CODE>bzip2_compressor</CODE></A></DT>
<DT><A HREF='#basic_bzip2_decompressor'>Class template <CODE>bzip2_decompressor</CODE></A></DT>
<DT><A HREF='#bzip2_error'>Class <CODE>bzip2_error</CODE></A></DT>
</DL>
</DT>
<DT><A href='#examples'>Examples</A></DT>
<DT><A href='#installation'>Installation</A></DT>
</DL>
<A NAME='overview'>
<H2>Overview</H2>
<P>
The class templates <A HREF="#basic_bzip2_compressor"><CODE>basic_bzip2_compressor</CODE></A> and <A HREF="#basic_bzip2_decompressor"><CODE>basic_bzip2_decompressor</CODE></A> perform compression and decompression using Julian Seward's libbzip2 compression library (<A CLASS='bib_ref' HREF='../bibliography.html#seward'>[Seward]</A>).
</P>
<P>
The bzip2 Filters are <A HREF='../concepts/dual_use_filter.html'>DualUseFilters</A> 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.
</P>
<A NAME='acknowledgments'>
<H2>Acknowledgments</H2>
<P>
The bzip2 Filters were influences by the work of Jeff Garland (<A CLASS='bib_ref' HREF='../bibliography.html#garland'>[Garland]</A>) and Jonathan de Halleux (<A CLASS='bib_ref' HREF='../bibliography.html#de_halleux'>[de Halleux]</A>).
</P>
Thanks to <A HREF="mailto:jseward@acm.org">Julian Seward</A> for making his excellent library available to the public with a <A HREF="http://www.boost.org/more/lib_guide.htm#Requirements">Boost-compatible</A> license.
<A NAME='headers'>
<H2>Headers</H2>
<DL>
<DT><A CLASS='header' HREF='../../../../boost/iostreams/filter/bzip2.hpp'><CODE>&lt;boost/iostreams/filter/bzip2.hpp&gt;</CODE></A></DT>
</DL>
<A NAME='synopsis'>
<H2>Synopsis</H2>
<PRE CLASS='broken_ie'><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
<SPAN CLASS="keyword">namespace</SPAN> <A CLASS="documented" HREF="#constants">bzip2</A> {
<SPAN CLASS='comment'>// Error codes</SPAN>
<SPAN CLASS="keyword">extern</SPAN> <SPAN CLASS="keyword">const</SPAN> <SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#data_error">data_error</A>;
<SPAN CLASS="keyword">extern</SPAN> <SPAN CLASS="keyword">const</SPAN> <SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#data_error_magic">data_error_magic</A>;
<SPAN CLASS="keyword">extern</SPAN> <SPAN CLASS="keyword">const</SPAN> <SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#config_error">config_error</A>;
} <SPAN CLASS='comment'>// End namespace boost::iostreams::bzip2</SPAN>
<SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#bzip2_params">bzip2_params</A>;
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<<SPAN CLASS="keyword">char</SPAN>> >
<SPAN CLASS="keyword">struc</SPAN>t <A CLASS="documented" HREF="#basic_bzip2_compressor">basic_bzip2_compressor</A>;
<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<<SPAN CLASS="keyword">char</SPAN>> >
<SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#basic_bzip2_decompressor">basic_bzip2_decompressor</A>;
<SPAN CLASS="keyword">typedef</SPAN> basic_bzip2_compressor<> <SPAN CLASS="defined">bzip2_compressor</SPAN>;
<SPAN CLASS="keyword">typedef</SPAN> basic_bzip2_decompressor<> <SPAN CLASS="defined">bzip2_decompressor</SPAN>;
<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#bzip2_error">bzip2_error</A>;
} } <SPAN CLASS='comment'>// End namespace boost::io</SPAN></PRE>
<A NAME='reference'>
<H2>Reference</H2>
<A NAME='constants'>
<H3>Namespace <CODE>boost::iostreams::bzip2</CODE></H3>
<P>The namespace <CODE>boost::iostreams::bzip2</CODE> contains integral error codes. The constants have the following interpretations. <I>See</I> <A CLASS='bib_ref' HREF='../bibliography.html#seward'>[Seward]</A> for additional details.</P>
<TABLE STYLE='margin-left:2em' BORDER=1 CELLPADDING=4>
<TR><TH>Constant</TH><TH>Interpretation</TH></TR>
<TR>
<TD VALIGN='top'><A NAME='data_error'></A><CODE>data_error</CODE></TD>
<TD>Indicates that the compressed data stream is corrupted. Equal to <CODE>BZ_DATA_ERROR</CODE>.</TD>
</TR>
<TR>
<TD VALIGN='top'><A NAME='data_error_magic'></A><CODE>data_error_magic</CODE></TD>
<TD>Indicates that the compressed data stream does not begin with the 'magic' sequence <CODE>'B' 'Z' 'h'</CODE>. Equal to <CODE>BZ_DATA_ERROR_MAGIC</CODE>.</TD>
</TR>
<TR>
<TD VALIGN='top'><A NAME='config_error'></A><CODE>config_error</CODE></TD>
<TD>Indicates that libbzip2 has been improperly configured for the current platform. Equal to <CODE>BZ_CONFIG_ERROR</CODE>.</TD>
</TR>
</TABLE>
<A NAME='bzip2_params'>
<H3>Class <CODE>bzip2_params</CODE></H3>
<H4>Description</H4>
<P>Encapsulates the parameters used to configure <A HREF="#basic_bzip2_compressor"><CODE>basic_bzip2_compressor</CODE></A> and <A HREF="#basic_bzip2_decompressor"><CODE>basic_bzip2_decompressor</CODE></A>.</P>
<H4>Synopsis</H4>
<PRE CLASS='broken_ie'><SPAN CLASS="keyword">struct</SPAN> <SPAN CLASS="defined">bzip2_params</SPAN> {
<SPAN CLASS='comment'>// Non-explicit constructor for compression</SPAN>
<A CLASS="documented" HREF="#bzip2_params_constructors">bzip2_params</A>( <SPAN CLASS="keyword">int</SPAN> block_size = <SPAN CLASS='omitted'>default value</SPAN>,
<SPAN CLASS="keyword">int</SPAN> work_factor = <SPAN CLASS='omitted'>default value</SPAN> );
<SPAN CLASS='comment'>// Constructor for decompression.</SPAN>
<A CLASS="documented" HREF="#bzip2_params_constructors">bzip2_params</A>( <SPAN CLASS="keyword">bool</SPAN> small );
<SPAN CLASS="keyword">union</SPAN> {
<SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#block_size">block_size</A>; <SPAN CLASS='comment'>// For compression</SPAN>
<SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#small">small</A>; <SPAN CLASS='comment'>// For decompression</SPAN>
};
<SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#work_factor">work_factor</A>; <SPAN CLASS='comment'>// For compression</SPAN>
};</PRE>
<A NAME='bzip2_params_constructors'>
<H4><CODE>bzip2_params::bzip2_params</CODE></H4>
<PRE CLASS='broken_ie'> <B>bzip2_params</B>( <SPAN CLASS="keyword">int</SPAN> block_size = <SPAN CLASS='omitted'>default value</SPAN>,
<SPAN CLASS="keyword">int</SPAN> work_factor = <SPAN CLASS='omitted'>default value</SPAN> );
<B>bzip2_params</B>( <SPAN CLASS="keyword">bool</SPAN> small );</PRE>
<P>The first member constructs a <CODE>bzip2_params</CODE> object for configuring <CODE>basic_bzip2_compressor</CODE>.</P>
<TABLE STYLE='margin-left:2em' BORDER=0 CELLPADDING=2>
<TR>
<TR>
<TD VALIGN='top'><A NAME='block_size'></A><I>block_size</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
<TD>Block size to use for compression; actual block size is <CODE>100000 * </CODE><I>block_size</I>. Must be in range <CODE>1-9</CODE>.</TD>
</TR>
<TR>
<TD VALIGN='top'><A NAME='work_factor'></A><I>work_factor</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
<TD>Controls behavior of compression with worst case data. Must be in the range 0-250.</TD>
</TR>
</TABLE>
<P>The second constructs a <CODE>bzip2_params</CODE> object for configuring <CODE>basic_bzip2_decompressor</CODE>.</P>
<TABLE STYLE='margin-left:2em' BORDER=0 CELLPADDING=2>
<TR>
<TR>
<TD VALIGN='top'><A NAME='small'></A><I>small</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
<TD>Indicates whether a slower decompression algorithm, using less memory, should be used.</TD>
</TR>
</TABLE>
<P><I>See</I> <A CLASS='bib_ref' HREF='../bibliography.html#seward'>[Seward]</A> for additional details.</P>
<A NAME='basic_bzip2_compressor'>
<H3>Class template <CODE>basic_bzip2_compressor</CODE></H3>
<H4>Description</H4>
Model of <A HREF='../concepts/dual_use_filter.html'>DualUseFilter</A> which performs compression using libbzip2 (<A CLASS='bib_ref' HREF='../bibliography.html#seward'>[Seward]</A>).
<H4>Synopsis</H4>
<PRE CLASS='broken_ie'><SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#basic_bzip2_compressor_params">Alloc</A> = std::allocator&lt;<SPAN CLASS="keyword">char</SPAN>&gt; &gt;
<SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#basic_bzip2_compressor_params">basic_bzip2_compressor</A> {
<SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">char</SPAN> char_type;
<SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS='omitted'>implementation-defined</SPAN> io_category;
<A CLASS="documented" HREF="#basic_bzip2_compressor_constructors">basic_bzip2_compressor</A>( <SPAN CLASS="keyword">const</SPAN> <A CLASS="documented" HREF="#bzip2_params">bzip2_params</A>& = <SPAN CLASS="omitted">bzip2::default_block_size</SPAN>,
std::streamsize buffer_size = <SPAN CLASS='omitted'>default value</SPAN> );
<SPAN CLASS='omitted'>...</SPAN>
};
<SPAN CLASS="keyword">typedef</SPAN> <A CLASS="documented" HREF="#basic_bzip2_compressor">basic_bzip2_compressor</A><> <SPAN CLASS="defined">bzip2_compressor</SPAN>;</PRE>
<A NAME='basic_bzip2_compressor_params'></A>
<H4>Template Parameters</H4>
<TABLE STYLE='margin-left:2em' BORDER=0 CELLPADDING=2>
<TR>
<TR>
<TD VALIGN='top'><I>Alloc</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
<TD>A C++ standard library allocator type (<A CLASS='bib_ref' HREF='../bibliography.html#iso'>[ISO]</A>, 20.1.5), used to allocate a character buffer and to configure libbzip2.</TD>
</TR>
</TABLE>
<A NAME='basic_bzip2_compressor_constructors'></A>
<H4><CODE>basic_bzip2_compressor::basic_bzip2_compressor</CODE></H4>
<PRE CLASS='broken_ie'> <B>basic_bzip2_compressor</B>(<SPAN CLASS="keyword">const</SPAN> <A CLASS="documented" HREF="#bzip2_params">bzip2_params</A>&, std::streamsize buffer_size);</PRE>
<P>Constructs an instance of <CODE>basic_bzip2_compressor</CODE> with the given parameters and buffer size. Since a <A CLASS="documented" HREF="#bzip2_params"><CODE>bzip2_params</CODE></A> object is implicitly constructible from an <CODE>int</CODE> representing a block size, an <CODE>int</CODE> may be passed as the first constructor argument.</P>
<A NAME='basic_bzip2_decompressor'>
<H3>Class template <CODE>basic_bzip2_decompressor</CODE></H3>
<H4>Description</H4>
Model of <A HREF='../concepts/dual_use_filter.html'>DualUseFilter</A> which performs decompression using libbzip2 (<A CLASS='bib_ref' HREF='../bibliography.html#seward'>[Seward]</A>).
<H4>Synopsis</H4>
<PRE CLASS='broken_ie'><SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#basic_bzip2_decompressor_params">Alloc</A> = std::allocator&lt;<SPAN CLASS="keyword">char</SPAN>&gt; &gt;
<SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#basic_bzip2_decompressor_params">basic_bzip2_decompressor</A> {
<SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">char</SPAN> char_type;
<SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS='omitted'>implementation-defined</SPAN> io_category;
<A CLASS="documented" HREF="#basic_bzip2_decompressor_constructors">basic_bzip2_decompressor</A>( <SPAN CLASS="keyword">bool</SPAN> small = <SPAN CLASS="omitted">false</SPAN>,
std::streamsize buffer_size =
<SPAN CLASS='omitted'>default value</SPAN> );
<SPAN CLASS='omitted'>...</SPAN>
};
<SPAN CLASS="keyword">typedef</SPAN> <A CLASS="documented" HREF="#basic_bzip2_decompressor">basic_bzip2_decompressor</A><> <SPAN CLASS="defined">bzip2_decompressor</SPAN>;</PRE>
<A NAME='basic_bzip2_decompressor_params'></A>
<H4>Template Parameters</H4>
<TABLE STYLE='margin-left:2em' BORDER=0 CELLPADDING=2>
<TR>
<TR>
<TD VALIGN='top'><I>Alloc</I></TD><TD WIDTH='2em' VALIGN='top'>-</TD>
<TD>A C++ standard library allocator type (<A CLASS='bib_ref' HREF='../bibliography.html#iso'>[ISO]</A>, 20.1.5), used to allocate a character buffer and to configure libbzip2.</TD>
</TR>
</TABLE>
<A NAME='basic_bzip2_decompressor_constructors'></A>
<H4><CODE>basic_bzip2_decompressor::basic_bzip2_decompressor</CODE></H4>
<PRE CLASS='broken_ie'> <A CLASS="documented" HREF="#basic_bzip2_decompressor_constructors">basic_bzip2_decompressor</A>(<SPAN CLASS="keyword">bool</SPAN> small, std::streamsize buffer_size);</PRE>
<P>Constructs an instance of <CODE>basic_bzip2_decompressor</CODE> with the given value for <A HREF="#small">small</A> and the given buffer size.</P>
<A NAME='bzip2_error'>
<H3>Class <CODE>bzip2_error</CODE></H3>
<H4>Description</H4>
Used by the bzip2 Filters to report errors.
<H4>Synopsis</H4>
<PRE CLASS='broken_ie'><SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">bzip2_error</SPAN> : <SPAN CLASS="keyword">public</SPAN> std::ios_base::failure {
<SPAN CLASS="keyword">public:</SPAN>
<A CLASS="documented" HREF="#bzip2_error_constructor">bzip2_error</A>(<SPAN CLASS="keyword">int</SPAN> error);
<SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#bzip2_error_error">error</A>() const;
};</PRE>
<A NAME='bzip2_error_constructor'></A>
<H4><CODE>bzip2_error::bzip2_error</CODE></H4>
<PRE CLASS='broken_ie'> <B>bzip2_error</B>(<SPAN CLASS="keyword">int</SPAN> error);</PRE>
<P>Constructs an instance of <CODE>bzip2_error</CODE> with the given error code from the namespace <A HREF="#constants"><CODE>boost::iostreams::bzip2</CODE></A>.</P>
<A NAME='bzip2_error_error'></A>
<H4><CODE>bzip2_error::error</CODE></H4>
<PRE CLASS='broken_ie'> <SPAN CLASS="keyword">void</SPAN> <B>error</B>() <SPAN CLASS="keyword">const</SPAN>;</PRE>
<P>Returns an error code from the namespace <A HREF="#constants"><CODE>boost::iostreams::bzip2</CODE></A>.</P>
<A NAME='examples'>
<H2>Examples</H2>
The following code decompresses data from a file and writes it to standard output.
<PRE CLASS='broken_ie'><SPAN CLASS='preprocessor'>#include</SPAN> <SPAN CLASS='literal'>&lt;fstream&gt;</SPAN>
<SPAN CLASS='preprocessor'>#include</SPAN> <SPAN CLASS='literal'>&lt;iostream&gt;</SPAN>
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS='header' HREF="../../../../boost/iostreams/filtering_streambuf.hpp"><SPAN CLASS='literal'>&lt;boost/iostreams/filtering_streambuf.hpp&gt;</SPAN></A>
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS='header' HREF="../../../../boost/iostreams/copy.hpp"><SPAN CLASS='literal'>&lt;boost/iostreams/copy.hpp&gt;</SPAN></A>
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS='header' HREF="../../../../boost/iostreams/filter/bzip2.hpp"><SPAN CLASS='literal'>&lt;boost/iostreams/filter/bzip2.hpp&gt;</SPAN></A>
int main()
{
<SPAN CLASS="keyword">using</SPAN> <SPAN CLASS="keyword">namespace</SPAN> std;
ifstream file(<SPAN CLASS='literal'>"hello.bz2"</SPAN>, ios_base::in | ios_base::binary);
filtering_streambuf&lt;input&gt; in;
in.push(bzip2_decompressor());
in.push(file);
boost::iostreams::copy(in, cout);
}</PRE>
<A NAME='installation'>
<H3>Installation</H3>
<P>
The bzip2 Filters depend on the source file <A CLASS='header' HREF='../../src/bzip2.cpp'><CODE>&lt;libs/src/bzip2.cpp&gt;</CODE></A>. This source file uses the header <CODE>"bzlib.h"</CODE> from the libbzip2 library. Code using these Filters must be linked against libbzip2 binaries, which are available on most UNIX systems and which can be obtained for Windows systems <!-- <A HREF='http://www.gzip.org/bzip2/contrib/index.html'> --><SPAN STYLE='text-decoration:underline'>here</SPAN> (currently broken)<!-- </A> -->. Alternatively, binaries can be build from the source code (<A CLASS='bib_ref' HREF='../bibliography.html#seward'>[Seward]</A>).
</P>
<!-- Adler's obfuscated address is copied from his homepage -->
<!-- Begin Footer -->
<HR>
<P CLASS='copyright'>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
20 May, 2004
<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
</P>
<P CLASS='copyright'>&copy; Copyright Jonathan Turkanis, 2004</P>
<P CLASS='copyright'>
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF='http://www.boost.org/LICENSE_1_0.txt'>http://www.boost.org/LICENSE_1_0.txt</A>)
</P>
<!-- End Footer -->
</BODY>