Compress::Raw::Bzip2#

📦 std

Low-level interface to the bzip2 compression library.

Compress::Raw::Bzip2 is the layer underneath IO::Compress::Bzip2 and IO::Uncompress::Bunzip2, and what Archive::Tar uses for .tbz archives. It gives direct access to libbz2’s streaming compressor (Compress::Raw::Bzip2) and decompressor (Compress::Raw::Bunzip2) and the BZ_* status constants. Most programs are better served by IO::Compress::Bzip2 and friends; this module is for code that needs the streams themselves.

use Compress::Raw::Bzip2;

my $data = "hello, world\n" x 100;

# Compress: one bzdeflate call per chunk, bzclose at the end.
my ($bz, $status) = Compress::Raw::Bzip2->new(1, 9);   # append, 900k blocks
$status == BZ_OK or die "new: $status";
my $packed = '';
$bz->bzdeflate($data, $packed) == BZ_RUN_OK or die;
$bz->bzclose($packed) == BZ_STREAM_END or die;
printf "%d -> %d bytes\n", $bz->uncompressedBytes, $bz->compressedBytes;
# 1300 -> 66 bytes

# Uncompress: bzinflate eats its input and says BZ_STREAM_END at the end.
my $bunz = Compress::Raw::Bunzip2->new;
my $out = '';
$status = $bunz->bzinflate($packed, $out);
print "status: $status, round trip ", ($out eq $data ? "ok" : "BAD"), "\n";
# status: End of Stream, round trip ok

Every status is a dualvar: numeric BZ_* and the message text, so $status == BZ_STREAM_END and "$status" both work. bzdeflate, bzflush and bzclose append to the output buffer when the object was made with appendOut; bzinflate consumes its input when made with consume and, with limitOutput, decompresses at most one buffer’s worth per call.

This is a native implementation of the XS half of Compress::Raw::Bzip2 2.218; Compress/Raw/Bzip2.pm is upstream’s own. libbz2 is the system’s libbz2.so.1, loaded when the module is first used.

Differences from upstream#

None.

Functions#

Other Functions#

bzlibversion#

Compress::Raw::Bzip2::bzlibversion(): the version string of the libbz2 this process loaded, such as “1.0.8, 13-Jul-2019”.

new#

Compress::Raw::Bzip2->new([$appendOut, $blockSize100k, $workfactor, $verbosity]): a compressor. In list context also the status, BZ_OK on success.

DispStream#

$bz->DispStream([$message]): prints the stream’s state to stdout, for debugging.

bzdeflate#

$bz->bzdeflate($input, $output): compresses $input, appending to (or replacing, without appendOut) $output. Returns BZ_RUN_OK on success.

bzclose#

$bz->bzclose($output): ends the stream, writing what is pending and the end-of-stream marker into $output. Returns BZ_STREAM_END.

bzflush#

$bz->bzflush($output): writes what is pending into $output without ending the stream. Returns BZ_RUN_OK.

total_in_lo32#

$bz->total_in_lo32(): bytes taken in so far (low 32 bits).

total_out_lo32#

$bz->total_out_lo32(): bytes put out so far (low 32 bits).

compressedBytes#

$bz->compressedBytes(): compressed bytes produced so far.

uncompressedBytes#

$bz->uncompressedBytes(): uncompressed bytes taken in so far.