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 52Thanks 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><boost/iostreams/filter/bzip2.hpp></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><<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<<SPAN CLASS="keyword">char</SPAN>> > 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><<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<<SPAN CLASS="keyword">char</SPAN>> > 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<> <SPAN CLASS="defined">bzip2_compressor</SPAN>; 85<SPAN CLASS="keyword">typedef</SPAN> basic_bzip2_decompressor<> <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 178Model 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><<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#basic_bzip2_compressor_params">Alloc</A> = std::allocator<<SPAN CLASS="keyword">char</SPAN>> > 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>& = <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<> <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>&, 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 217Model 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><<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#basic_bzip2_decompressor_params">Alloc</A> = std::allocator<<SPAN CLASS="keyword">char</SPAN>> > 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<> <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 257Used 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 284The 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"><fstream></SPAN> 287<SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal"><iostream></SPAN> 288<SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/filtering_streambuf.hpp"><SPAN CLASS="literal"><boost/iostreams/filtering_streambuf.hpp></SPAN></A> 289<SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/copy.hpp"><SPAN CLASS="literal"><boost/iostreams/copy.hpp></SPAN></A> 290<SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/filter/bzip2.hpp"><SPAN CLASS="literal"><boost/iostreams/filter/bzip2.hpp></SPAN></A> 291 292int 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<input> 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">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" 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>