package Compress::LZ4;
use strict;
use warnings;
use Exporter qw(import);
use XSLoader;
our $VERSION = '0.25';
our $XS_VERSION = $VERSION;
$VERSION = eval $VERSION;
XSLoader::load(__PACKAGE__, $XS_VERSION);
our @EXPORT = qw(
compress compress_hc decompress uncompress
lz4_compress lz4_compress_hc lz4_decompress lz4_uncompress
);
1;
__END__
=head1 NAME
Compress::LZ4 - Perl interface to the LZ4 (de)compressor
=head1 SYNOPSIS
use Compress::LZ4;
my $compressed = compress($bytes);
my $decompressed = decompress($compressed);
=head1 DESCRIPTION
The C<Compress::LZ4> module provides an interface to the LZ4 (de)compressor.
=head1 FUNCTIONS
=head2 compress
$compressed = compress($bytes [, $level])
Compresses the given buffer and returns the resulting bytes. The input buffer
can be either a scalar or a scalar reference. The default acceleration level
(1) can be changed, with each additional level providing ~3% increase in
speed; the compression level will be negatively affected.
=head2 compress_hc
$compressed = compress_hc($bytes [, $level])
A higher-compression, but slower, version of C<compress>. The default
compression level (9) can be changed if an optional value (0-16) is given.
=head2 decompress
=head2 uncompress
$bytes = decompress($compressed)
Decompresses the given buffer and returns the resulting bytes. The input
buffer can be either a scalar or a scalar reference.
On error (in case of corrupted data) undef is returned.
=head1 COMPATIBILITY
This library does not produce output that is compatible with the official
frame format. Because LZ4 did not define a container format until long after
it was released, many bindings, including this one, prepend the original data
size to the compressed data as a little-endian 4-byte integer.
If you are dealing with raw data from an external source that does not format
the data this way, you need to use the following functions:
=head2 lz4_compress
=head2 lz4_compress_hc
Same as C<compress>/C<compress_hc> but does not add the length header.
=head2 lz4_decompress
=head2 lz4_uncompress
$bytes = decompress($compressed, $original_data_size)
Same as C<decompress>/C<uncompress> but also requires the original data size
to be given.
=head1 PERFORMANCE
This distribution contains a benchmarking script which compares several
modules available on CPAN. These are the results on a MacBook
2.6GHz Core i5 (64-bit) with Perl 5.24.1:
Compressible data (10 KiB) - compression
----------------------------------------
Compress::LZ4::compress 8 670690/s 6550 MiB/s 1.152%
Compress::LZ4::compress 649176/s 6340 MiB/s 1.152%
Compress::Snappy::compress 367492/s 3589 MiB/s 5.332%
Compress::LZF::compress 127765/s 1248 MiB/s 1.865%
Compress::LZ4::compress_hc 84620/s 826 MiB/s 1.152%
Compress::Zlib::compress 15514/s 152 MiB/s 1.201%
Compress::Bzip2::compress 246/s 2 MiB/s 2.070%
Compressible data (10 KiB) - decompression
------------------------------------------
Compress::LZF::decompress 1262620/s 12330 MiB/s
Compress::LZ4::decompress 819200/s 8000 MiB/s
Compress::Snappy::decompress 619934/s 6054 MiB/s
Compress::Zlib::uncompress 65163/s 636 MiB/s
Compress::Bzip2::decompress 12679/s 124 MiB/s
Uncompressible data (10 KiB) - compression
------------------------------------------
Compress::LZ4::compress 8 2102098/s 20528 MiB/s 109.231%
Compress::LZ4::compress 1854792/s 18113 MiB/s 109.231%
Compress::Snappy::compress 1619124/s 15812 MiB/s 104.615%
Compress::LZF::compress 1349269/s 13176 MiB/s 101.538%
Compress::LZ4::compress_hc 96376/s 941 MiB/s 109.231%
Compress::Zlib::compress 66370/s 648 MiB/s 112.308%
Compress::Bzip2::compress 54098/s 528 MiB/s 201.538%
Uncompressible data (10 KiB) - decompression
--------------------------------------------
Compress::LZF::decompress 5004566/s 48873 MiB/s
Compress::LZ4::decompress 4915199/s 48000 MiB/s
Compress::Snappy::decompress 4906438/s 47914 MiB/s
Compress::Zlib::uncompress 355071/s 3467 MiB/s
Compress::Bzip2::decompress 175812/s 1717 MiB/s
=head1 SEE ALSO
L<http://lz4.org/>
=head1 REQUESTS AND BUGS
Please report any bugs or feature requests to
L<http://rt.cpan.org/Public/Bug/Report.html?Queue=Compress-LZ4>. I will be
notified, and then you'll automatically be notified of progress on your bug as
I make changes.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Compress::LZ4
You can also look for information at:
=over
=item * GitHub Source Repository
L<https://github.com/gray/compress-lz4>
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/Compress-LZ4>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/Compress-LZ4>
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/Public/Dist/Display.html?Name=Compress-LZ4>
=item * Search CPAN
L<http://search.cpan.org/dist/Compress-LZ4/>
=back
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2012-2017 gray <gray at cpan.org>, all rights reserved.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
=head1 AUTHOR
gray, <gray at cpan.org>
=cut