module Zlib - Documentation for Ruby 3.3

# module Zlib

This module provides access to the zlib library. `Zlib` is designed to be a portable, free, general-purpose, legally unencumbered – that is, not covered by any patents – lossless data-compression library for use on virtually any computer hardware and operating system.

The zlib compression library provides in-memory compression and decompression functions, including integrity checks of the uncompressed data.

The zlib compressed data format is described in RFC 1950, which is a wrapper around a deflate stream which is described in RFC 1951.

The library also supports reading and writing files in gzip (.gz) format with an interface similar to that of `IO`. The gzip format is described in RFC 1952 which is also a wrapper around a deflate stream.

The zlib format was designed to be compact and fast for use in memory and on communications channels. The gzip format was designed for single-file compression on file systems, has a larger header than zlib to maintain directory information, and uses a different, slower check method than zlib.

See your system’s zlib.h for further information about zlib

## Sample usage¶ ↑

Using the wrapper to compress strings with default parameters is quite simple:

    require "zlib"

    data_to_compress = File.read("don_quixote.txt")

    puts "Input size: #{data_to_compress.size}"
    #=> Input size: 2347740

    data_compressed = Zlib::Deflate.deflate(data_to_compress)

    puts "Compressed size: #{data_compressed.size}"
    #=> Compressed size: 887238

    uncompressed_data = Zlib::Inflate.inflate(data_compressed)

    puts "Uncompressed data is: #{uncompressed_data}"
    #=> Uncompressed data is: The Project Gutenberg EBook of Don Quixote...

## `Class` tree¶ ↑

- `Zlib::Deflate`

- `Zlib::Inflate`

- `Zlib::ZStream`

- `Zlib::Error`

  - `Zlib::StreamEnd`

  - `Zlib::NeedDict`

  - `Zlib::DataError`

  - `Zlib::StreamError`

  - `Zlib::MemError`

  - `Zlib::BufError`

  - `Zlib::VersionError`

  - `Zlib::InProgressError`

(if you have GZIP_SUPPORT)

- `Zlib::GzipReader`

- `Zlib::GzipWriter`

- `Zlib::GzipFile`

- `Zlib::GzipFile::Error`

  - `Zlib::GzipFile::LengthError`

  - `Zlib::GzipFile::CRCError`

  - `Zlib::GzipFile::NoFooter`

### Constants

ASCII

  Represents text data as guessed by deflate.

  NOTE: The underlying constant Z_ASCII was deprecated in favor of Z_TEXT in zlib 1.2.2. New applications should not use this constant.

  See `Zlib::Deflate#data_type`.

BEST_COMPRESSION

  Slowest compression level, but with the best space savings.

BEST_SPEED

  Fastest compression level, but with the lowest space savings.

BINARY

  Represents binary data as guessed by deflate.

  See `Zlib::Deflate#data_type`.

DEFAULT_COMPRESSION

  Default compression level which is a good trade-off between space and time

DEFAULT_STRATEGY

  Default deflate strategy which is used for normal data.

DEF_MEM_LEVEL

  The default memory level for allocating zlib deflate compression state.

FILTERED

  `Deflate` strategy for data produced by a filter (or predictor). The effect of `FILTERED` is to force more Huffman codes and less string matching; it is somewhat intermediate between `DEFAULT_STRATEGY` and `HUFFMAN_ONLY`. Filtered data consists mostly of small values with a somewhat random distribution.

FINISH

  Processes all pending input and flushes pending output.

FIXED

  `Deflate` strategy which prevents the use of dynamic Huffman codes, allowing for a simpler decoder for specialized applications.

FULL_FLUSH

  Flushes all output as with `SYNC_FLUSH`, and the compression state is reset so that decompression can restart from this point if previous compressed data has been damaged or if random access is desired. Like `SYNC_FLUSH`, using `FULL_FLUSH` too often can seriously degrade compression.

HUFFMAN_ONLY

  `Deflate` strategy which uses Huffman codes only (no string matching).

MAX_MEM_LEVEL

  The maximum memory level for allocating zlib deflate compression state.

MAX_WBITS

  The maximum size of the zlib history buffer. Note that zlib allows larger values to enable different inflate modes. See `Zlib::Inflate.new` for details.

NO_COMPRESSION

  No compression, passes through data untouched. Use this for appending pre-compressed data to a deflate stream.

NO_FLUSH

  `NO_FLUSH` is the default flush method and allows deflate to decide how much data to accumulate before producing output in order to maximize compression.

OS_AMIGA

  OS code for Amiga hosts

OS_ATARI

  OS code for Atari hosts

OS_CODE

  The OS code of current host

OS_CPM

  OS code for CP/M hosts

OS_MACOS

  OS code for Mac OS hosts

OS_MSDOS

  OS code for MSDOS hosts

OS_OS2

  OS code for OS2 hosts

OS_QDOS

  OS code for QDOS hosts

OS_RISCOS

  OS code for RISC OS hosts

OS_TOPS20

  OS code for TOPS-20 hosts

OS_UNIX

  OS code for UNIX hosts

OS_UNKNOWN

  OS code for unknown hosts

OS_VMCMS

  OS code for VM OS hosts

OS_VMS

  OS code for VMS hosts

OS_WIN32

  OS code for `Win32` hosts

OS_ZSYSTEM

  OS code for Z-System hosts

RLE

  `Deflate` compression strategy designed to be almost as fast as `HUFFMAN_ONLY`, but give better compression for PNG image data.

SYNC_FLUSH

  The `SYNC_FLUSH` method flushes all pending output to the output buffer and the output is aligned on a byte boundary. Flushing may degrade compression so it should be used only when necessary, such as at a request or response boundary for a network stream.

TEXT

  Represents text data as guessed by deflate.

  See `Zlib::Deflate#data_type`.

UNKNOWN

  Represents an unknown data type as guessed by deflate.

  See `Zlib::Deflate#data_type`.

VERSION

  The Ruby/zlib version string.

ZLIB_VERSION

  The string which represents the version of zlib.h

### Public Class Methods

adler32(string, adler) click to toggle source

Calculates Adler-32 checksum for `string`, and returns updated value of `adler`. If `string` is omitted, it returns the Adler-32 initial value. If `adler` is omitted, it assumes that the initial value is given to `adler`. If `string` is an `IO` instance, reads from the `IO` until the `IO` returns nil and returns Adler-32 of all read data.

Example usage:

    require "zlib"

    data = "foo"
    puts "Adler32 checksum: #{Zlib.adler32(data).to_s(16)}"
    #=> Adler32 checksum: 2820145

    static VALUE
    rb_zlib_adler32(int argc, VALUE *argv, VALUE klass)
    {
        return do_checksum(argc, argv, adler32);
    }

adler32_combine(adler1, adler2, len2) click to toggle source

Combine two Adler-32 check values in to one. `adler1` is the first Adler-32 value, `adler2` is the second Adler-32 value. `len2` is the length of the string used to generate `adler2`.

    static VALUE
    rb_zlib_adler32_combine(VALUE klass, VALUE adler1, VALUE adler2, VALUE len2)
    {
        return ULONG2NUM(
            adler32_combine(NUM2ULONG(adler1), NUM2ULONG(adler2), NUM2LONG(len2)));
    }

crc32(string, crc) click to toggle source

Calculates CRC checksum for `string`, and returns updated value of `crc`. If `string` is omitted, it returns the CRC initial value. If `crc` is omitted, it assumes that the initial value is given to `crc`. If `string` is an `IO` instance, reads from the `IO` until the `IO` returns nil and returns CRC checksum of all read data.

FIXME: expression.

    static VALUE
    rb_zlib_crc32(int argc, VALUE *argv, VALUE klass)
    {
        return do_checksum(argc, argv, crc32);
    }

crc32_combine(crc1, crc2, len2) click to toggle source

Combine two CRC-32 check values in to one. `crc1` is the first CRC-32 value, `crc2` is the second CRC-32 value. `len2` is the length of the string used to generate `crc2`.

    static VALUE
    rb_zlib_crc32_combine(VALUE klass, VALUE crc1, VALUE crc2, VALUE len2)
    {
        return ULONG2NUM(
            crc32_combine(NUM2ULONG(crc1), NUM2ULONG(crc2), NUM2LONG(len2)));
    }

crc_table() click to toggle source

Returns the table for calculating CRC checksum as an array.

    static VALUE
    rb_zlib_crc_table(VALUE obj)
    {
    #if !defined(HAVE_TYPE_Z_CRC_T)
        /* z_crc_t is defined since zlib-1.2.7. */
        typedef unsigned long z_crc_t;
    #endif
        const z_crc_t *crctbl;
        VALUE dst;
        int i;

        crctbl = get_crc_table();
        dst = rb_ary_new2(256);

        for (i = 0; i < 256; i++) {
            rb_ary_push(dst, rb_uint2inum(crctbl[i]));
        }
        return dst;
    }

deflate(string[, level]) click to toggle source
Zlib::Deflate.deflate(string[, level])

Compresses the given `string`. Valid values of level are `Zlib::NO_COMPRESSION`, `Zlib::BEST_SPEED`, `Zlib::BEST_COMPRESSION`, `Zlib::DEFAULT_COMPRESSION`, or an integer from 0 to 9.

This method is almost equivalent to the following code:

    def deflate(string, level)
      z = Zlib::Deflate.new(level)
      dst = z.deflate(string, Zlib::FINISH)
      z.close
      dst
    end

See also `Zlib.inflate`

    static VALUE
    rb_deflate_s_deflate(int argc, VALUE *argv, VALUE klass)
    {
        struct zstream z;
        VALUE src, level, dst, args[2];
        int err, lev;

        rb_scan_args(argc, argv, "11", &src, &level);

        lev = ARG_LEVEL(level);
        StringValue(src);
        zstream_init_deflate(&z);
        err = deflateInit(&z.stream, lev);
        if (err != Z_OK) {
            raise_zlib_error(err, z.stream.msg);
        }
        ZSTREAM_READY(&z);

        args[0] = (VALUE)&z;
        args[1] = src;
        dst = rb_ensure(deflate_run, (VALUE)args, zstream_ensure_end, (VALUE)&z);

        return dst;
    }

gunzip(src) → String click to toggle source

Decode the given gzipped `string`.

This method is almost equivalent to the following code:

    def gunzip(string)
      sio = StringIO.new(string)
      gz = Zlib::GzipReader.new(sio, encoding: Encoding::ASCII_8BIT)
      gz.read
    ensure
      gz&.close
    end

See also `Zlib.gzip`

    static VALUE
    zlib_gunzip(VALUE klass, VALUE src)
    {
        struct gzfile gz0;
        struct gzfile *gz = &gz0;
        int err;

        StringValue(src);

        gzfile_init(gz, &inflate_funcs, zlib_gunzip_end);
        err = inflateInit2(&gz->z.stream, -MAX_WBITS);
        if (err != Z_OK) {
            raise_zlib_error(err, gz->z.stream.msg);
        }
        gz->io = Qundef;
        gz->z.input = src;
        ZSTREAM_READY(&gz->z);
        return rb_ensure(zlib_gunzip_run, (VALUE)gz, zlib_gzip_ensure, (VALUE)gz);
    }

gzip(src, level: nil, strategy: nil) → String click to toggle source

Gzip the given `string`. Valid values of level are `Zlib::NO_COMPRESSION`, `Zlib::BEST_SPEED`, `Zlib::BEST_COMPRESSION`, `Zlib::DEFAULT_COMPRESSION` (default), or an integer from 0 to 9.

This method is almost equivalent to the following code:

    def gzip(string, level: nil, strategy: nil)
      sio = StringIO.new
      sio.binmode
      gz = Zlib::GzipWriter.new(sio, level, strategy)
      gz.write(string)
      gz.close
      sio.string
    end

See also `Zlib.gunzip`

    static VALUE
    zlib_s_gzip(int argc, VALUE *argv, VALUE klass)
    {
        struct gzfile gz0;
        struct gzfile *gz = &gz0;
        int err;
        VALUE src, opts, level=Qnil, strategy=Qnil, args[2];

        if (OPTHASH_GIVEN_P(opts)) {
            ID keyword_ids[2];
            VALUE kwargs[2];
            keyword_ids[0] = id_level;
            keyword_ids[1] = id_strategy;
            rb_get_kwargs(opts, keyword_ids, 0, 2, kwargs);
            if (kwargs[0] != Qundef) {
                level = kwargs[0];
            }
            if (kwargs[1] != Qundef) {
                strategy = kwargs[1];
            }
        }
        rb_scan_args(argc, argv, "10", &src);
        StringValue(src);
        gzfile_init(gz, &deflate_funcs, zlib_gzip_end);
        gz->level = ARG_LEVEL(level);
        err = deflateInit2(&gz->z.stream, gz->level, Z_DEFLATED,
                           -MAX_WBITS, DEF_MEM_LEVEL, ARG_STRATEGY(strategy));
        if (err != Z_OK) {
            zlib_gzip_end(gz);
            raise_zlib_error(err, gz->z.stream.msg);
        }
        ZSTREAM_READY(&gz->z);
        args[0] = (VALUE)gz;
        args[1] = src;
        return rb_ensure(zlib_gzip_run, (VALUE)args, zlib_gzip_ensure, (VALUE)gz);
    }

inflate(string) click to toggle source
Zlib::Inflate.inflate(string)

Decompresses `string`. Raises a `Zlib::NeedDict` exception if a preset dictionary is needed for decompression.

This method is almost equivalent to the following code:

    def inflate(string)
      zstream = Zlib::Inflate.new
      buf = zstream.inflate(string)
      zstream.finish
      zstream.close
      buf
    end

See also `Zlib.deflate`

    static VALUE
    rb_inflate_s_inflate(VALUE obj, VALUE src)
    {
        struct zstream z;
        VALUE dst, args[2];
        int err;

        StringValue(src);
        zstream_init_inflate(&z);
        err = inflateInit(&z.stream);
        if (err != Z_OK) {
            raise_zlib_error(err, z.stream.msg);
        }
        ZSTREAM_READY(&z);

        args[0] = (VALUE)&z;
        args[1] = src;
        dst = rb_ensure(inflate_run, (VALUE)args, zstream_ensure_end, (VALUE)&z);

        return dst;
    }

zlib_version() click to toggle source

Returns the string which represents the version of zlib library.

    static VALUE
    rb_zlib_version(VALUE klass)
    {
        return rb_str_new2(zlibVersion());
    }