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
    <https://github.com/ebiggers/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.

