=encoding UTF-8

=head1 NAME

Gzip::Faster - gzip and gunzip, without the fuss

=head1 SYNOPSIS

    
    use Gzip::Faster;
    my $gzipped = gzip ($input);
    my $roundtrip = gunzip ($gzipped);
    if ($roundtrip ne $input) { die; }
    gzip_to_file ($input, 'file.gz');
    $roundtrip = gunzip_file ('file.gz');
    if ($roundtrip ne $input) { die; }


=head1 DESCRIPTION

This module compresses to and decompresses from the gzip format.

=head1 FUNCTIONS

=head2 gzip

    my $zipped = gzip ($stuff);

This compresses C<$stuff> into the gzip format. The return value is
the compressed version of C<$stuff>.

=head2 gunzip

    my $stuff = gunzip ($zipped);

This uncompresses C<$zipped> and returns the result of the
uncompression. It returns the undefined value if C<$zipped> is the
undefined value or an empty string. Otherwise, it throws a fatal error
if C<$zipped> is not in the gzip format.

=head2 gzip_file

    my $zipped = gzip_file ('file');

This reads the contents of F<file> into memory and then runs L</gzip>
on the file's contents. The return value and the possible errors are
the same as L</gzip>, plus this may also throw an error if C<open>
fails.

=head2 gunzip_file

    my $stuff = gunzip_file ('file.gz');

This reads the contents of F<file.gz> into memory and then runs
L</gunzip> on the file's contents. The return value and the possible
errors are the same as L</gunzip>, plus this may also throw an error
if C<open> fails.

=head2 gzip_to_file

    gzip_to_file ($plain, 'file.gz');

This compresses C<$plain> in memory using L</gzip> and writes the
compressed content to 'file.gz'. There is no return value. The errors
are the same as L</gzip>, plus this may also throw an error if C<open>
fails. As of this version, it does not write any gzip header
information to F<file.gz>.

=head1 PERFORMANCE

This section compares the performance of Gzip::Faster with
L<IO::Compress::Gzip>/L<IO::Uncompress::Gunzip> and
L<Compress::Raw::Zlib>. According to my results, Gzip::Faster is about
five times faster to load, seven times faster to compress, and
twenty-five times faster to uncompress than the IO::Uncompress
modules. Round trips are about ten times faster with Gzip::Faster.

Compared to the L<Compress::Raw::Zlib> modules, load times are about
one and a half times faster, round trips are about three times faster,
compression is about two and a half times faster, and decompression is
about six times faster.

The versions used in this test are as follows:

    $IO::Compress::Gzip::VERSION = 2.064
    $IO::Uncompress::Gunzip::VERSION = 2.064
    $Compress::Raw::Zlib::VERSION = 2.065
    $Gzip::Faster::VERSION = 0.08_01


Here is a comparison of load times:

    
                Rate Load IOUG Load IOCG  Load CRZ   Load GF
    Load IOUG 14.4/s        --       -4%      -67%      -78%
    Load IOCG 15.1/s        4%        --      -65%      -77%
    Load CRZ  43.2/s      200%      187%        --      -35%
    Load GF   66.5/s      361%      341%       54%        --


Here is a comparison of a round-trip:

    
                          Rate IO::Compress::Gzip Compress::Raw::Zlib   Gzip::Faster
    IO::Compress::Gzip   635/s                 --                -71%           -90%
    Compress::Raw::Zlib 2160/s               240%                  --           -67%
    Gzip::Faster        6584/s               937%                205%             --


Here is a comparison of gzip (compression) only:

    
                                   Rate IO::Compress::Gzip Compress::Raw::Zlib::Deflate Gzip::Faster
    IO::Compress::Gzip           1240/s                 --                         -60%         -84%
    Compress::Raw::Zlib::Deflate 3083/s               149%                           --         -61%
    Gzip::Faster                 7940/s               540%                         158%           --


Here is a comparison of gunzip (decompression) only:

    
                                    Rate IO::Uncompress::Gunzip Compress::Raw::Zlib::Inflate Gzip::Faster
    IO::Uncompress::Gunzip        1390/s                     --                         -74%         -96%
    Compress::Raw::Zlib::Inflate  5396/s                   288%                           --         -83%
    Gzip::Faster                 31220/s                  2146%                         479%           --


The test file is in "examples/benchmark.pl" in the distribution.

=head1 BUGS

The module source code includes disabled functionality to round-trip
Perl flags. I applied this to preserving Perl's "utf8" flag. However,
the mechanism I used trips a browser bug in the Firefox web browser
where it produces a content encoding error message. Thus this
functionality is disabled. Please refer to the file
F<gzip-faster-perl.c> in the distribution, the relevant parts are
commented out with a macro C<COPY_PERL>.

The module doesn't check whether the input of L</gzip> is already
gzipped, and it doesn't check whether the compression was
effective. That is, it doesn't check whether the output of L</gzip> is
actually smaller than the input.

=head1 ACKNOWLEDGEMENTS

zgrim reported an important bug related to zlib.

Aristotle Pagaltzis contributed the benchmarking code for
L<Compress::Raw::Zlib>.

=head1 AUTHOR, COPYRIGHT AND LICENCE

Ben Bullock <bkb@cpan.org>. Copyright (C) 2014 Ben Bullock. This
software may be used, modified, distributed under the same licence as
Perl itself.

=cut

