libs/iostreams/doc/classes/bzip2.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4     <TITLE>Bzip2 Filters</TITLE>
   5     <LINK REL="stylesheet" HREF="../../../../boost.css">
   6     <LINK REL="stylesheet" HREF="../theme/iostreams.css">
   7 </HEAD>
   8 <BODY>
   9
  10 <!-- Begin Banner -->
  11
  12     <H1 CLASS="title">Bzip2 Filters</H1>
  13     <HR CLASS="banner">
  14
  15 <!-- End Banner -->
  16
  17 <DL class="page-index">
  18   <DT><A href="#overview">Overview</A></DT>
  19   <DT><A href="#acknowledgments">Acknowledgments</A></DT>
  20   <DT><A href="#headers">Headers</A></DT>
  21   <DT><A href="#synopsis">Synopsis</A></DT>
  22   <DT><A HREF="#reference">Reference</A>
  23     <DL class="page-index">
  24       <DT><A HREF="#constants">namespace <CODE>boost::iostreams::bzip2</CODE></A></DT>
  25       <DT><A HREF="#bzip2_params">Class <CODE>bzip2_params</CODE></A></DT>
  26       <DT><A HREF="#basic_bzip2_compressor">Class template <CODE>bzip2_compressor</CODE></A></DT>
  27       <DT><A HREF="#basic_bzip2_decompressor">Class template <CODE>bzip2_decompressor</CODE></A></DT>
  28       <DT><A HREF="#bzip2_error">Class <CODE>bzip2_error</CODE></A></DT>
  29     </DL>
  30   </DT>
  31   <DT><A href="#examples">Examples</A></DT>
  32   <DT><A href="#installation">Installation</A></DT>
  33 </DL>
  34
  35 <A NAME="overview"></A>
  36 <H2>Overview</H2>
  37
  38 <P>
  39     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>).
  40 </P>
  41 <P>
  42     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.
  43 </P>
  44
  45 <A NAME="acknowledgments"></A>
  46 <H2>Acknowledgments</H2>
  47
  48 <P>
  49     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>).
  50 </P>
  51
  52 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.
  53
  54 <A NAME="headers"></A>
  55 <H2>Headers</H2>
  56
  57 <DL>
  58   <DT><A CLASS="header" HREF="../../../../boost/iostreams/filter/bzip2.hpp"><CODE>&lt;boost/iostreams/filter/bzip2.hpp&gt;</CODE></A></DT>
  59 </DL>
  60
  61 <A NAME="synopsis"></A>
  62 <H2>Synopsis</H2>
  63
  64 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
  65
  66 <SPAN CLASS="keyword">namespace</SPAN> <A CLASS="documented" HREF="#constants">bzip2</A> {
  67
  68     <SPAN CLASS="comment">// Error codes</SPAN>
  69
  70 <SPAN CLASS="keyword">extern</SPAN> <SPAN CLASS="keyword">const</SPAN> <SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#data_error">data_error</A>;
  71 <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>;
  72 <SPAN CLASS="keyword">extern</SPAN> <SPAN CLASS="keyword">const</SPAN> <SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#config_error">config_error</A>;
  73
  74 }   <SPAN CLASS="comment">// End namespace boost::iostreams::bzip2</SPAN>
  75
  76 <SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#bzip2_params">bzip2_params</A>;
  77
  78 <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<<SPAN CLASS="keyword">char</SPAN>&gt; >
  79 <SPAN CLASS="keyword">struc</SPAN>t <A CLASS="documented" HREF="#basic_bzip2_compressor">basic_bzip2_compressor</A>;
  80
  81 <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<<SPAN CLASS="keyword">char</SPAN>&gt; >
  82 <SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#basic_bzip2_decompressor">basic_bzip2_decompressor</A>;
  83
  84 <SPAN CLASS="keyword">typedef</SPAN> basic_bzip2_compressor&lt;&gt;   <SPAN CLASS="defined">bzip2_compressor</SPAN>;
  85 <SPAN CLASS="keyword">typedef</SPAN> basic_bzip2_decompressor&lt;&gt; <SPAN CLASS="defined">bzip2_decompressor</SPAN>;
  86
  87 <SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#bzip2_error">bzip2_error</A>;
  88
  89 } } <SPAN CLASS="comment">// End namespace boost::io</SPAN></PRE>
  90
  91 <A NAME="reference"></A>
  92 <H2>Reference</H2>
  93
  94 <A NAME="constants"></A>
  95 <H3>Namespace <CODE>boost::iostreams::bzip2</CODE></H3>
  96
  97 <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>
  98
  99 <TABLE STYLE="margin-left:2em" BORDER=1 CELLPADDING=4>
 100 <TR><TH>Constant</TH><TH>Interpretation</TH></TR>
 101     <TR>
 102         <TD VALIGN="top"><A NAME="data_error"></A><CODE>data_error</CODE></TD>
 103         <TD>Indicates that the compressed data stream is corrupted. Equal to <CODE>BZ_DATA_ERROR</CODE>.</TD>
 104     </TR>
 105     <TR>
 106         <TD VALIGN="top"><A NAME="data_error_magic"></A><CODE>data_error_magic</CODE></TD>
 107         <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>
 108     </TR>
 109     <TR>
 110         <TD VALIGN="top"><A NAME="config_error"></A><CODE>config_error</CODE></TD>
 111         <TD>Indicates that libbzip2 has been improperly configured for the current platform. Equal to <CODE>BZ_CONFIG_ERROR</CODE>.</TD>
 112     </TR>
 113 </TABLE>
 114
 115 <A NAME="bzip2_params"></A>
 116 <H3>Class <CODE>bzip2_params</CODE></H3>
 117
 118 <H4>Description</H4>
 119
 120 <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>
 121
 122 <H4>Synopsis</H4>
 123
 124 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">struct</SPAN> <SPAN CLASS="defined">bzip2_params</SPAN> {
 125
 126     <SPAN CLASS="comment">// Non-explicit constructor for compression</SPAN>
 127     <A CLASS="documented" HREF="#bzip2_params_constructors">bzip2_params</A>( <SPAN CLASS="keyword">int</SPAN> block_size   = <SPAN CLASS="omitted">default value</SPAN>,
 128                   <SPAN CLASS="keyword">int</SPAN> work_factor  = <SPAN CLASS="omitted">default value</SPAN> );
 129
 130     <SPAN CLASS="comment">// Constructor for decompression.</SPAN>
 131     <A CLASS="documented" HREF="#bzip2_params_constructors">bzip2_params</A>( <SPAN CLASS="keyword">bool</SPAN> small );
 132
 133     <SPAN CLASS="keyword">union</SPAN> {
 134         <SPAN CLASS="keyword">int</SPAN>   <A CLASS="documented" HREF="#block_size">block_size</A>;    <SPAN CLASS="comment">// For compression</SPAN>
 135         <SPAN CLASS="keyword">bool</SPAN>  <A CLASS="documented" HREF="#small">small</A>;         <SPAN CLASS="comment">// For decompression</SPAN>
 136     };
 137     <SPAN CLASS="keyword">int</SPAN>       <A CLASS="documented" HREF="#work_factor">work_factor</A>;   <SPAN CLASS="comment">// For compression</SPAN>
 138 };</PRE>
 139
 140 <A NAME="bzip2_params_constructors"></A>
 141 <H4><CODE>bzip2_params::bzip2_params</CODE></H4>
 142
 143 <PRE CLASS="broken_ie">    bzip2_params( <SPAN CLASS="keyword">int</SPAN> block_size   = <SPAN CLASS="omitted">default value</SPAN>,
 144                   <SPAN CLASS="keyword">int</SPAN> work_factor  = <SPAN CLASS="omitted">default value</SPAN> );
 145     bzip2_params( <SPAN CLASS="keyword">bool</SPAN> small );</PRE>
 146
 147 <P>The first member constructs a <CODE>bzip2_params</CODE> object for configuring <CODE>basic_bzip2_compressor</CODE>.</P>
 148
 149 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 150 <TR>
 151     <TR>
 152         <TD VALIGN="top"><A NAME="block_size"></A><I>block_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 153         <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>
 154     </TR>
 155     <TR>
 156         <TD VALIGN="top"><A NAME="work_factor"></A><I>work_factor</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 157         <TD>Controls behavior of compression with worst case data. Must be in the range 0-250.</TD>
 158     </TR>
 159 </TABLE>
 160
 161 <P>The second constructs a <CODE>bzip2_params</CODE> object for configuring <CODE>basic_bzip2_decompressor</CODE>.</P>
 162
 163 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 164 <TR>
 165     <TR>
 166         <TD VALIGN="top"><A NAME="small"></A><I>small</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 167         <TD>Indicates whether a slower decompression algorithm, using less memory, should be used.</TD>
 168     </TR>
 169 </TABLE>
 170
 171 <P><I>See</I> <A CLASS="bib_ref" HREF="../bibliography.html#seward">[Seward]</A> for additional details.</P>
 172
 173 <A NAME="basic_bzip2_compressor"></A>
 174 <H3>Class template <CODE>basic_bzip2_compressor</CODE></H3>
 175
 176 <H4>Description</H4>
 177
 178 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>).
 179
 180 <H4>Synopsis</H4>
 181
 182 <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;
 183 <SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#basic_bzip2_compressor_params">basic_bzip2_compressor</A> {
 184     <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">char</SPAN>                    char_type;
 185     <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="omitted">implementation-defined</SPAN>  category;
 186
 187     <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>&amp; = <SPAN CLASS="omitted">bzip2::default_block_size</SPAN>,
 188                             std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN> );
 189     <SPAN CLASS="omitted">...</SPAN>
 190 };
 191
 192 <SPAN CLASS="keyword">typedef</SPAN> basic_bzip2_compressor&lt;&gt; <SPAN CLASS="defined">bzip2_compressor</SPAN>;</PRE>
 193
 194 <A NAME="basic_bzip2_compressor_params"></A>
 195 <H4>Template Parameters</H4>
 196
 197 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 198 <TR>
 199     <TR>
 200         <TD VALIGN="top"><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 201         <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>
 202     </TR>
 203 </TABLE>
 204
 205 <A NAME="basic_bzip2_compressor_constructors"></A>
 206 <H4><CODE>basic_bzip2_compressor::basic_bzip2_compressor</CODE></H4>
 207
 208 <PRE CLASS="broken_ie">    basic_bzip2_compressor(<SPAN CLASS="keyword">const</SPAN> <A CLASS="documented" HREF="#bzip2_params">bzip2_params</A>&amp;, std::streamsize buffer_size);</PRE>
 209
 210 <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>
 211
 212 <A NAME="basic_bzip2_decompressor"></A>
 213 <H3>Class template <CODE>basic_bzip2_decompressor</CODE></H3>
 214
 215 <H4>Description</H4>
 216
 217 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>).
 218
 219 <H4>Synopsis</H4>
 220
 221 <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;
 222 <SPAN CLASS="keyword">struct</SPAN> <A CLASS="documented" HREF="#basic_bzip2_decompressor_params">basic_bzip2_decompressor</A> {
 223     <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">char</SPAN>                    char_type;
 224     <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="omitted">implementation-defined</SPAN>  category;
 225
 226     <A CLASS="documented" HREF="#basic_bzip2_decompressor_constructors">basic_bzip2_decompressor</A>( <SPAN CLASS="keyword">bool</SPAN> small = <SPAN CLASS="omitted">false</SPAN>,
 227                               std::streamsize buffer_size =
 228                                   <SPAN CLASS="omitted">default value</SPAN> );
 229     <SPAN CLASS="omitted">...</SPAN>
 230 };
 231
 232 <SPAN CLASS="keyword">typedef</SPAN> basic_bzip2_decompressor&lt;&gt; <SPAN CLASS="defined">bzip2_decompressor</SPAN>;</PRE>
 233
 234 <A NAME="basic_bzip2_decompressor_params"></A>
 235 <H4>Template Parameters</H4>
 236
 237 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 238 <TR>
 239     <TR>
 240         <TD VALIGN="top"><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 241         <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>
 242     </TR>
 243 </TABLE>
 244
 245 <A NAME="basic_bzip2_decompressor_constructors"></A>
 246 <H4><CODE>basic_bzip2_decompressor::basic_bzip2_decompressor</CODE></H4>
 247
 248 <PRE CLASS="broken_ie">    basic_bzip2_decompressor(<SPAN CLASS="keyword">bool</SPAN> small, std::streamsize buffer_size);</PRE>
 249
 250 <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>
 251
 252 <A NAME="bzip2_error"></A>
 253 <H3>Class <CODE>bzip2_error</CODE></H3>
 254
 255 <H4>Description</H4>
 256
 257 Used by the bzip2 Filters to report errors.
 258
 259 <H4>Synopsis</H4>
 260
 261 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">bzip2_error</SPAN> : <SPAN CLASS="keyword">public</SPAN> std::ios_base::failure {
 262 <SPAN CLASS="keyword">public:</SPAN>
 263     <A CLASS="documented" HREF="#bzip2_error_constructor">bzip2_error</A>(<SPAN CLASS="keyword">int</SPAN> error);
 264     <SPAN CLASS="keyword">int</SPAN> <A CLASS="documented" HREF="#bzip2_error_error">error</A>() const;
 265 };</PRE>
 266
 267 <A NAME="bzip2_error_constructor"></A>
 268 <H4><CODE>bzip2_error::bzip2_error</CODE></H4>
 269
 270 <PRE CLASS="broken_ie">    bzip2_error(<SPAN CLASS="keyword">int</SPAN> error);</PRE>
 271
 272 <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>
 273
 274 <A NAME="bzip2_error_error"></A>
 275 <H4><CODE>bzip2_error::error</CODE></H4>
 276
 277 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">void</SPAN> error() <SPAN CLASS="keyword">const</SPAN>;</PRE>
 278
 279 <P>Returns an error code from the namespace <A HREF="#constants"><CODE>boost::iostreams::bzip2</CODE></A>.</P>
 280
 281 <A NAME="examples"></A>
 282 <H2>Examples</H2>
 283
 284 The following code decompresses data from a file and writes it to standard output.
 285
 286 <PRE CLASS="broken_ie"><SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal">&lt;fstream&gt;</SPAN>
 287 <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal">&lt;iostream&gt;</SPAN>
 288 <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>
 289 <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/copy.hpp"><SPAN CLASS="literal">&lt;boost/iostreams/copy.hpp&gt;</SPAN></A>
 290 <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>
 291
 292 int main()
 293 {
 294     <SPAN CLASS="keyword">using</SPAN> <SPAN CLASS="keyword">namespace</SPAN> std;
 295     <SPAN CLASS="keyword">using</SPAN> <SPAN CLASS="keyword">namespace</SPAN> boost::iostreams;
 296
 297     ifstream file(<SPAN CLASS="literal">"hello.bz2"</SPAN>, ios_base::in | ios_base::binary);
 298     filtering_streambuf&lt;input&gt; in;
 299     in.push(bzip2_decompressor());
 300     in.push(file);
 301     boost::iostreams::copy(in, cout);
 302 }</PRE>
 303
 304 <A NAME="installation"></A>
 305 <H3>Installation</H3>
 306
 307 <P>
 308      The bzip2 Filters depend on the third-party libbz2 library, which is <I>not</I> 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 <A HREF="http://www.bzip.org/" TARGET="_top">libbz2 homepage</A>. For details on configuring the build system to find your libbz2 installation, please see <A HREF="../installation.html">Installation</A>.
 309 </P>
 310
 311 <!-- Adler's obfuscated address is copied from his homepage -->
 312
 313 <!-- Begin Footer -->
 314
 315 <HR>
 316
 317 <P CLASS="copyright">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; Copyright 2004-2007 <a href="http://www.coderage.com/turkanis/" target="_top">Jonathan Turkanis</a></P>
 318 <P CLASS="copyright">
 319     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>)
 320 </P>
 321
 322 <!-- End Footer -->
 323
 324 </BODY>