Compress::Bzip2 - interface to the bzip2 compression library
use Compress::Bzip2;
$dest = Compress::Bzip2::compress($source, [$level]);
$dest = Compress::Bzip2::decompress($source);
The Compress::Bzip2 module provides a Perl interface to the Bzip2 compression library (see "AUTHOR" for details about where to get Bzip2). A relevant subset of the functionality provided by Bzip2 is available in Compress::Bzip2.
You may pass in a reference to a string wherever a string is required.
You can retrieve the library version using the version function.
$dest = Compress::Bzip2::compress($string)
Compress a string using the default compression level, returning a string containing compressed data.
$dest = Compress::Bzip2::compress($string, $level)
Compress string, using the chosen compression level (either 1 or 9). Return a string containing the compressed data.
On error undef is returned.
$dest = Compress::Bzip2::decompress($string)
Decompress the data in string, returning a string containing the decompressed data.
On error undef is returned.
If a function reports an error by returning undef, call error to get the error string. In list context, returns a list of (string, libbz2 code).
if(not defined $dest)
{
print "compression failed: ".Compress::Bzip2::error();
}
To compress a larger volume of data, the streamed compression interface may be of use. For both compression and decompression, you create a stream object, add data to it, then call finish when done:
my $stream = Compress::Bzip2::compress_init();
while(my $data = read_data())
{
write_data($stream->add($data));
}
write_data($stream->finish());
Note that if you want to be able to decompress the result using the decompress method, you need to call the prefix method and prefix the result:
my $original = Compress::Bzip2::decompress($stream->prefix().$output);
The streaming decompression interface is similar; just replace compress_init with decompress_init. The optional parameters each takes as well as some other methods on the stream object are described below:
Takes named parameters:
1 or 9, as for compress (defaults to 1)
bzip2 library work factor (0-250; if missing or 0 defaults to 30)
buffer size to use (defaults to 8192 - 8K)
Takes named parameters:
if set (1), use alternative algorithm (slower but uses less memory) (default 0)
buffer size to use (defaults to 8192 - 8K)
Add data to be compressed/decompressed. Returns whatever output is available (possibly none, if it's still buffering it), or undef on error.
Finish the operation; takes an optional final data string. Whatever is returned completes the output; returns undef on error.
Like the function, but applies to the current object only. Note that errors in a stream object are also returned by the function.
Total bytes passed to the stream.
Total bytes received from the stream.
The Compress::Bzip2 module was written by Gawdi Azem azemgi@rupert.informatik.uni-stuttgart.de and is now maintained by Marco Carnut kiko@tempest.com.br. The streaming interface and error information were added by David Robins dbrobins@davidrobins.net.
1.00 First public release of Compress::Bzip2.
1.02 Added BZ2_ prefixes so that it works with libbz2 versions >1.0
1.03 Added error reporting, and streaming functions, fixed some compression errors, added tests.
