/ 
Deflate-Faster-0.02
/ Deflate::Faster

Name

Deflate::Faster - fast gzip, zlib and raw DEFLATE using libdeflate

Synopsis

use Deflate::Faster qw(:all);

my $gz    = gzip($data);          # optional level: gzip($data, 1)
my $plain = gunzip($gz);

my $z   = deflate($data);         # zlib (RFC 1950)
my $raw = deflate_raw($data);     # raw DEFLATE (RFC 1951)

gzip_to_file($data, 'out.gz');
my $back = gunzip_file('out.gz');

my $df = Deflate::Faster->new;
$df->level(1);
$df->max_size(10 * 1024 * 1024);
my $out = $df->zip($data);
my $in  = $df->unzip($out);

Description

A drop-in replacement for Gzip::Faster built on libdeflate. Compression and decompression work on whole buffers in memory. Levels run from 0 (stored) to 12, default 6. Compressor and decompressor states are cached per thread.

Functions

gzip, deflate, deflate_raw

my $out = gzip($plain, $level);

Compress to gzip, zlib or raw DEFLATE. $level is optional; undef or -1 selects the default. Undefined or empty input warns and returns undef.

gunzip, inflate, inflate_raw

my $plain = gunzip($zipped);

Decompress. gunzip also accepts zlib streams and concatenated gzip members, and checks header CRCs. Corrupt, truncated or trailing data croaks. Undefined or empty input warns and returns undef.

gzip_file

my $zipped = gzip_file($file, %options);

Options: level, file_name (default $file), mod_time (default the file's mtime) and copy_perl_flags. Pass file_name => '' or mod_time => 0 to omit them.

gunzip_file

my $plain = gunzip_file($file, %options);

Options: max_size, copy_perl_flags, and scalar references file_name => \$name and mod_time => \$mtime to receive the header fields.

gzip_to_file, gunzip_to_file

gzip_to_file($plain, $file, %options);
gunzip_to_file($zipped, $file, %options);

Write the result to $file, truncating it. gzip_to_file takes the gzip_file options without their defaults; gunzip_to_file takes max_size and always writes bytes.

Methods

new

my $df = Deflate::Faster->new;

zip, unzip

my $out   = $df->zip($plain);
my $plain = $df->unzip($out);

Use the object's format and settings. zip writes file_name and mod_time into the gzip header, then clears file_name. unzip clears both, then sets them from the first gzip member's header.

gzip_format, raw

$df->gzip_format(1);
$df->raw(1);

Select gzip (the default) or raw DEFLATE. With both off the format is zlib.

level

$df->level($level);

0 to 12. undef or -1 selects 6; lower values warn and select 6; higher values warn and select 12.

max_size

$df->max_size($bytes);

Croak when decompressed output would exceed $bytes. Values below 1 and undef mean unlimited; strings convert as Perl numbers do. Without a limit, a gzip trailer claiming a large size can make a buffer grow to 8 times the output already decoded.

file_name

$df->file_name($name);
my $name = $df->file_name;

Gzip header file name, stored as Latin-1 and cut at the first NUL. A name with characters beyond Latin-1 croaks at zip.

mod_time

$df->mod_time($epoch);
my $epoch = $df->mod_time;

Gzip header time, an unsigned 32-bit integer. Out-of-range and non-numeric values warn and are clamped.

copy_perl_flags

$df->copy_perl_flags(1);

Record Perl's UTF-8 flag in the gzip header, in the same format as Gzip::Faster, and restore it on unzip when any member carries it and the output is valid UTF-8. Gzip format only.

Differences from Gzip::Faster

  • Concatenated gzip members decompress; Gzip::Faster croaks.

  • Trailing bytes after a stream croak.

  • Header CRCs (FHCRC) are checked.

  • Levels 0 to 12, and the procedural functions take an optional level.

  • unzip clears file_name and mod_time in every format.

  • gzip_file keeps its file name and mtime defaults when other options are given.

  • File names are written as Latin-1; wider characters croak.

  • mod_time is clamped to 32 bits instead of wrapping.

  • new blesses into the calling subclass.

  • The custom header OS byte is 0xff, and error messages differ.

Diagnostics

Empty input
Attempt to compress empty string
Attempt to uncompress empty string

(W) Undefined or empty input; undef is returned.

Data input to inflate is not in libz format

(F) Corrupt, truncated or trailing data.

Uncompressed data exceeds max_size of %d bytes

(F) See "max_size".

Gzip file_name must contain only Latin-1 characters

(F) See "file_name".

Cannot set compression level to less than 0
Cannot set compression level to more than 12
Argument "%s" isn't numeric in compression level
Cannot set modification time to less than 0
Cannot set modification time to more than 4294967295
Argument "%s" isn't numeric in modification time

(W) See "level" and "mod_time".

Cannot write file name to non-scalar reference
Cannot write modification time to non-scalar reference

(W) A gunzip_file option was not a scalar reference.

Performance

Speed relative to Gzip::Faster on Linux x86_64, averaged over eight kinds of text per size (bench/bench_vs_gzip_faster.pl):

size     gzip level 6   gzip level 1   gunzip
72 B          5.8x           7.2x        1.0x
2 KB          3.6x           6.4x        1.3x
100 KB        1.3x           4.1x        3.4x
1 MB          1.4x           4.4x        3.4x

Threads

Cached engines are freed when their thread exits. Objects are not cloned into new threads.

Exports

gzip, gunzip, gzip_file, gunzip_file and gzip_to_file by default; deflate, inflate, deflate_raw, inflate_raw and gunzip_to_file on request; :all for everything.

See also

Gzip::Faster, Gzip::Libdeflate, Compress::Raw::Zlib

Author

vividsnow

License

This software is copyright (c) 2026 by vividsnow.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.