gzip

    my $zipped = gzip ($plain);

This compresses $plain into the gzip format. The return value is the compressed version of $plain.

gunzip

    my $plain = gunzip ($zipped);

This uncompresses $zipped and returns the result of the uncompression. It prints a warning and returns the undefined value if $zipped is the undefined value or an empty string. It throws a fatal error if $zipped is not in the gzip format.

gzip_file

    my $zipped = gzip_file ('file');

This reads the contents of file into memory and then runs "gzip" on the file's contents. The return value and the possible errors are the same as "gzip", plus this may also throw an error if "open" fails. To write a file name, use

    my $zipped = gzip_file ('file', file_name => 'file');

The modification time can also be written:

    my $zipped = gzip_file ('file', file_name => 'file', mod_time => time ());

"gzip_file" was added in version 0.04. File name writing was added in version 0.18. Modification time writing was added in version 0.19.

gunzip_file

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

This reads the contents of file.gz into memory and then runs "gunzip" on the file's contents. The return value and the possible errors are the same as "gunzip", plus this may also throw an error if "open" fails. To retrieve a file name, use

    my $plain = gunzip_file ('file.gz', file_name => \my $file_name);

Note that you must provide a scalar reference to the "file_name" argument. This reference is filled in with the file name information from the header of file.gz. If file.gz does not contain any file name information, $file_name will contain the undefined value.

The modification time can also be read from the header:

    my $plain = gunzip_file ('file.gz', file_name => \my $file_name,
                             mod_time => \my $mod_time);

"gunzip_file" was added in version 0.04. File name reading was added in version 0.18. Modification time reading was added in version 0.19.

gzip_to_file

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

This compresses $plain in memory using "gzip" and writes the compressed content to 'file.gz'. There is no return value. The errors are the same as "gzip", plus this may also throw an error if "open" fails. To write a file name, use

    gzip_to_file ($plain, 'file.gz', file_name => 'file');

"gzip_to_file" was added in version 0.08. File name writing was added in version 0.18. Modification time writing was added in version 0.19.

deflate

    my $deflated = deflate ($plain);

This compresses $plain into the deflate format. The deflate format is similar to the "gzip" format, except that it doesn't contain a gzip header. The output of "deflate" can be inflated either with "inflate" or with "gunzip".

To see an example of using "deflate" to write a PNG image file, see t/png.t <https://fastapi.metacpan.org/source/BKB/Gzip-Faster-0.21/t/png.t> in the module's tests.

"deflate" was added in version 0.16.

inflate

    my $inflated = inflate ($deflated);

This inflates the output of "deflate". For all practical purposes this is identical to "gunzip", and it's included only for completeness. In other words, you can use inflate and gunzip interchangeably.

"inflate" was added in version 0.16.

deflate_raw

"deflate_raw" was added in version 0.16.

inflate_raw

"inflate_raw" was added in version 0.16.

new

    my $gf = Gzip::Faster->new ();

Create a Gzip::Faster object. The return value defaults to gzip compression. This can be altered with "gzip_format" and "raw".

"new" was added in version 0.16.

zip

    my $zipped = $gf->zip ($plain);

Compress $plain. The type of compression can be set with "gzip" and "raw".

"zip" was added in version 0.16.

unzip

    my $plain = $gf->unzip ($zipped);

Uncompress $zipped. The type of uncompression can be set with "gzip" and "raw".

"unzip" was added in version 0.16.

copy_perl_flags

    $gf->copy_perl_flags (1);

Copy some of the Perl flags (currently the utf8 flag) into the header of the gzipped data.

Please see "Browser bugs and Gzip::Faster" for reasons why you might not want to use this feature.

This feature of the module was restored in version 0.16.

file_name

    my $filename = $gf->file_name ();
    $gf->file_name ('this.gz');
    my $zipped = $gf->zip ($something);

Get or set the file name in the compressed output. The file name is a feature of the gzip format which is used, for example, when you use the command "gzip -d file.gz". It tells "gzip" what to call the file after it's uncompressed.

The file_name method is only useful for the gzip format, since the deflate format does not have a header to store a name into. To prevent accidental re-use of a file name, when you set a file name with "file_name", then use "zip", the file name is deleted from the object, so it needs to be set each time "zip" is called. If you set a file name with "file_name" then call "unzip", that file name may be deleted.

The following example demonstrates storing and then retrieving the name:

    use Gzip::Faster;
    my $gf = Gzip::Faster->new ();
    $gf->file_name ("blash.gz");
    my $something = $gf->zip ("stuff");
    my $no = $gf->file_name ();
    if ($no) {
        print "WHAT?\n";
    }
    else {
        print "The file name has been deleted by the call to zip.\n";
    }
    my $gf2 = Gzip::Faster->new ();
    $gf2->unzip ($something);
    my $file_name = $gf2->file_name ();
    print "Got back file name $file_name\n";

produces output

    The file name has been deleted by the call to zip.
    Got back file name blash.gz

(This example is included as file-name.pl <https://fastapi.metacpan.org/source/BKB/Gzip-Faster-0.21/examples/file-name.pl> in the distribution.)

The module currently has a hard-coded limit of 1024 bytes as the maximum length of file name it can read back.

"file_name" was added in version 0.16.

gzip_format

    $gf->gzip_format (1);

Switch the compression between the "gzip format" and the "deflate format". A true value turns on the gzip format, and a false value turns on the deflate format. The default is gzip format. Switching on gzip format on an object automatically switches off "raw" format on the object.

"gzip_format" was added in version 0.16.

raw

    $gf->raw (1);

Switch between the raw deflate and deflate formats. A true value turns on the "raw deflate format", and a false value turns off the raw deflate format. Switching this on has the side effect of automatically switching off "gzip_format". Thus the sequence

    $gf->gzip_format (1);
    $gf->raw (1);
    $gf->raw (0);

puts $gf in the non-raw deflate format.

"raw" was added in version 0.16.

level

    $gf->level (9);

Set the level of compression, from 0 (no compression) to 9 (best compression). Values outside the levels cause a warning and the level to be set to the nearest valid value, for example a value of 100 causes the level to be set to 9. The higher the level of compression, the more time it takes to compute. The default value is a compromise between speed and quality of compression.

"level" was added in version 0.16.

mod_time

    $gf->mod_time (time ());
    my $mod_time = $gf->mod_time ();

Set or get the file modification time in the gzip header. The modification time is an unsigned integer which represents the number of seconds since the Unix epoch. This only applies to "gzip_format" compression.

"mod_time" was added in version 0.19.

Short text

Compared to Compress::Raw::Zlib, 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.069
    $IO::Uncompress::Gunzip::VERSION = 2.069
    $Compress::Raw::Zlib::VERSION = 2.069
    $Gzip::Faster::VERSION = 0.19

The size after compression is as follows:

    IO::Compress:Gzip size is 830 bytes.
    Compress::Raw::Zlib size is 830 bytes.
    Gzip::Faster size is 830 bytes.

Here is a comparison of load times:

                Rate Load IOUG Load IOCG  Load CRZ   Load GF
    Load IOUG 25.3/s        --       -4%      -66%      -77%
    Load IOCG 26.5/s        5%        --      -65%      -76%
    Load CRZ  75.1/s      197%      184%        --      -31%
    Load GF    109/s      330%      311%       45%        --

Here is a comparison of a round-trip:

                           Rate IO::Compress::Gzip Compress::Raw::Zlib  Gzip::Faster
    IO::Compress::Gzip   1309/s                 --                -66%          -90%
    Compress::Raw::Zlib  3888/s               197%                  --          -70%
    Gzip::Faster        12929/s               888%                233%            --

Here is a comparison of gzip (compression) only:

                                    Rate IO::Compress::Gzip Compress::Raw::Zlib::Deflate Gzip::Faster
    IO::Compress::Gzip            2567/s                 --                         -60%         -86%
    Compress::Raw::Zlib::Deflate  6491/s               153%                           --         -65%
    Gzip::Faster                 18338/s               614%                         183%           --

Here is a comparison of gunzip (decompression) only:

                                    Rate IO::Uncompress::Gunzip Compress::Raw::Zlib::Inflate Gzip::Faster
    IO::Uncompress::Gunzip        2818/s                     --                         -74%         -96%
    Compress::Raw::Zlib::Inflate 10997/s                   290%                           --         -84%
    Gzip::Faster                 69565/s                  2368%                         533%           --

Long text

The versions used in this test are as above.

The sizes are as follows:

    IO::Compress:Gzip size is 995387 bytes.
    Compress::Raw::Zlib size is 995387 bytes.
    Gzip::Faster size is 995823 bytes.

Note that the size of the file compressed with the command-line gzip, with the default compression, is identical to the size with Gzip::Faster::gzip, except for the 12 bytes in the file version used to store the file name:

    $ gzip --keep chinese.txt
    $ ls -l chinese.txt.gz 
    -rw-r--r--  1 ben  ben  995835 Oct 20 18:52 chinese.txt.gz

Here is a comparison of a round-trip:

                          Rate IO::Compress::Gzip Compress::Raw::Zlib   Gzip::Faster
    IO::Compress::Gzip  4.43/s                 --                 -3%            -8%
    Compress::Raw::Zlib 4.57/s                 3%                  --            -5%
    Gzip::Faster        4.81/s                 9%                  5%             --

Here is a comparison of gzip (compression) only:

                                   Rate IO::Compress::Gzip Compress::Raw::Zlib::Deflate Gzip::Faster
    IO::Compress::Gzip           5.04/s                 --                           0%          -6%
    Compress::Raw::Zlib::Deflate 5.04/s                 0%                           --          -6%
    Gzip::Faster                 5.36/s                 6%                           6%           --

Here is a comparison of gunzip (decompression) only:

                                   Rate IO::Uncompress::Gunzip Compress::Raw::Zlib::Inflate Gzip::Faster
    IO::Uncompress::Gunzip       36.8/s                     --                         -18%         -20%
    Compress::Raw::Zlib::Inflate 45.1/s                    23%                           --          -1%
    Gzip::Faster                 45.7/s                    24%                           1%           --

For longer files, Gzip::Faster is not much faster. The underlying library's speed is the main factor.

Browser bugs and Gzip::Faster

Using "copy_perl_flags" with utf8-encoded text trips a browser bug in the Firefox web browser where it produces a content encoding error message.

Using deflate rather than gzip compression trips browser bugs in older versions of Internet Explorer, which mistakenly say they can handle the deflate format, but in fact can only handle gzip format.

Ubuntu Linux

    sudo apt-get install zlib1g-dev

Windows

About gzip

These formats are formally described by RFC 1950 <https://tools.ietf.org/rfc/rfc1950.txt> (ZLIB Compressed Data Format Specification), RFC 1951 <https://tools.ietf.org/rfc/rfc1951.txt> (DEFLATE Compressed Data Format Specification), and RFC 1952 <https://tools.ietf.org/rfc/rfc1952.txt> (GZIP file format specification). The library "zlib" implements the formats.

Alternatives

Command-line gzip

To use the command line utility "gzip", use

    system ("gzip file");
    

or put the command in backquotes, like "`gzip file`".

mod_deflate and mod_gzip

These are Apache web server modules which compress web outputs immediately after you produce them, and before sending to the user.

PerlIO::gzip

This is a Perl extension to provide a PerlIO layer to gzip/gunzip. That means you can just add ":gzip" when you open a file to read or write compressed files:

    open my $in, "<:gzip", 'file.gz'

    open my $out, ">:gzip", 'file.gz'
    

and you never have to deal with the gzip format.

IO::Zlib

Compress::Zlib

Compress::Raw::Zlib

CGI::Compress::Gzip

IO::Compress::Gzip and IO::Uncompress::Gunzip

Gzip::RandomAccess - extract arbitrary bits of a gzip stream

Compress::Zopfli

This is a compress-only library by Google <https://www.google.com> for a gzip/deflate format compression.