123456789_123456789_123456789_123456789_123456789_

Module: Zlib

Relationships & Source Files
Namespace Children
Classes:
Exceptions:
Defined in: ext/zlib/zlib.c

Overview

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

  • Deflate

  • Inflate

  • ZStream

  • Error

    • Zlib::StreamEnd

    • Zlib::NeedDict

    • Zlib::DataError

    • Zlib::StreamError

    • Zlib::MemError

    • Zlib::BufError

    • Zlib::VersionError

    • Zlib::InProgressError

(if you have GZIP_SUPPORT)

Constant Summary

Class Method Summary

Class Method Details

.adler32(string, adler) (mod_func)

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
[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 450

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

.adler32_combine(adler1, adler2, len2) (mod_func)

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

[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 467

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) (mod_func)

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.

[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 490

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

.crc32_combine(crc1, crc2, len2) (mod_func)

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.

[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 507

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 (mod_func)

Returns the table for calculating CRC checksum as an array.

[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 522

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])

Alias for Deflate.deflate.

.gunzip(src) ⇒ String

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 .gzip

[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 4575

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

Gzip the given string. Valid values of level are NO_COMPRESSION, BEST_SPEED, BEST_COMPRESSION, 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 .gunzip

[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 4492

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)

Alias for Inflate.inflate.

[ GitHub ]

.zlib_version (mod_func)

Returns the string which represents the version of zlib library.

[ GitHub ]

  
# File 'ext/zlib/zlib.c', line 369

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