Files
iostreams/doc/classes/bzip2.html
Jonathan Turkanis 5b886642b4 switched to double quotes in HTML attributes
[SVN r27367]
2005-02-14 01:51:10 +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>