Module: Zlib

Defined in:
ext/zlib/zlib.c,
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

  • Zlib::Deflate

  • Zlib::Inflate

  • Zlib::ZStream

  • Zlib::Error

    • Zlib::StreamEnd

    • Zlib::NeedDict

    • Zlib::DataError

    • Zlib::StreamError

    • Zlib::MemError

    • Zlib::BufError

    • Zlib::VersionError

(if you have GZIP_SUPPORT)

  • Zlib::GzipReader

  • Zlib::GzipWriter

  • Zlib::GzipFile

  • Zlib::GzipFile::Error

    • Zlib::GzipFile::LengthError

    • Zlib::GzipFile::CRCError

    • Zlib::GzipFile::NoFooter

Defined Under Namespace

Classes: BufError, DataError, Deflate, Error, GzipFile, GzipReader, GzipWriter, Inflate, MemError, NeedDict, StreamEnd, StreamError, VersionError, ZStream

Constant Summary collapse

VERSION =

The Ruby/zlib version string.

rb_str_new2(RUBY_ZLIB_VERSION)
ZLIB_VERSION =

The string which represents the version of zlib.h

rb_str_new2(ZLIB_VERSION)
BINARY =

:Deflate#data_type.

Represents binary data as guessed by deflate.

See Zlib
ASCII =

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.

Represents text data as guessed by deflate.

NOTE
TEXT =

:Deflate#data_type.

Represents text data as guessed by deflate.

See Zlib
UNKNOWN =

:Deflate#data_type.

Represents an unknown data type as guessed by deflate.

See Zlib
NO_COMPRESSION =

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

INT2FIX(Z_NO_COMPRESSION)
BEST_SPEED =

Fastest compression level, but with the lowest space savings.

INT2FIX(Z_BEST_SPEED)
BEST_COMPRESSION =

Slowest compression level, but with the best space savings.

INT2FIX(Z_BEST_COMPRESSION)
DEFAULT_COMPRESSION =

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

INT2FIX(Z_DEFAULT_COMPRESSION)
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.

INT2FIX(Z_FILTERED)
HUFFMAN_ONLY =

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

INT2FIX(Z_HUFFMAN_ONLY)
RLE =

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

INT2FIX(Z_RLE)
FIXED =

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

INT2FIX(Z_FIXED)
DEFAULT_STRATEGY =

Default deflate strategy which is used for normal data.

INT2FIX(Z_DEFAULT_STRATEGY)
MAX_WBITS =

:Inflate.new for details.

The maximum size of the zlib history buffer.  Note that zlib allows
larger values to enable different inflate modes.  See Zlib
DEF_MEM_LEVEL =

The default memory level for allocating zlib deflate compression state.

INT2FIX(DEF_MEM_LEVEL)
MAX_MEM_LEVEL =

The maximum memory level for allocating zlib deflate compression state.

INT2FIX(MAX_MEM_LEVEL)
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.

INT2FIX(Z_NO_FLUSH)
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.

INT2FIX(Z_SYNC_FLUSH)
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.

INT2FIX(Z_FULL_FLUSH)
FINISH =

Processes all pending input and flushes pending output.

INT2FIX(Z_FINISH)
OS_CODE =

The OS code of current host

INT2FIX(OS_CODE)
OS_MSDOS =

OS code for MSDOS hosts

INT2FIX(OS_MSDOS)
OS_AMIGA =

OS code for Amiga hosts

INT2FIX(OS_AMIGA)
OS_VMS =

OS code for VMS hosts

INT2FIX(OS_VMS)
OS_UNIX =

OS code for UNIX hosts

INT2FIX(OS_UNIX)
OS_ATARI =

OS code for Atari hosts

INT2FIX(OS_ATARI)
OS_OS2 =

OS code for OS2 hosts

INT2FIX(OS_OS2)
OS_MACOS =

OS code for Mac OS hosts

INT2FIX(OS_MACOS)
OS_TOPS20 =

OS code for TOPS-20 hosts

INT2FIX(OS_TOPS20)
OS_WIN32 =

OS code for Win32 hosts

INT2FIX(OS_WIN32)
OS_VMCMS =

OS code for VM OS hosts

INT2FIX(OS_VMCMS)
OS_ZSYSTEM =

OS code for Z-System hosts

INT2FIX(OS_ZSYSTEM)
OS_CPM =

OS code for CP/M hosts

INT2FIX(OS_CPM)
OS_QDOS =

OS code for QDOS hosts

INT2FIX(OS_QDOS)
OS_RISCOS =

OS code for RISC OS hosts

INT2FIX(OS_RISCOS)
OS_UNKNOWN =

OS code for unknown hosts

INT2FIX(OS_UNKNOWN)

Class Method Summary collapse

Class Method Details

.adler32(*args) ⇒ Object

call-seq: Zlib.adler32(string, adler)

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



451
452
453
454
455
 
# File 'ext/zlib/zlib.c', line 451

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

.adler32_combine(adler1, adler2, len2) ⇒ Object

call-seq: Zlib.adler32_combine(adler1, adler2, len2)

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.



468
469
470
471
472
473
 
# File 'ext/zlib/zlib.c', line 468

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(*args) ⇒ Object

call-seq: Zlib.crc32(string, crc)

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.



491
492
493
494
495
 
# File 'ext/zlib/zlib.c', line 491

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

.crc32_combine(crc1, crc2, len2) ⇒ Object

call-seq: Zlib.crc32_combine(crc1, crc2, len2)

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.



508
509
510
511
512
513
 
# File 'ext/zlib/zlib.c', line 508

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 ⇒ Object

Returns the table for calculating CRC checksum as an array.



523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
 
# File 'ext/zlib/zlib.c', line 523

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(*args) ⇒ Object

call-seq:

Zlib.deflate(string[, level])
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



1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
 
# File 'ext/zlib/zlib.c', line 1698

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

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

Returns:

  • (String) 


4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
 
# File 'ext/zlib/zlib.c', line 4556

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

Returns:

  • (String) 


4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
 
# File 'ext/zlib/zlib.c', line 4473

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(src) ⇒ Object

call-seq:

Zlib.inflate(string)
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



2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
 
# File 'ext/zlib/zlib.c', line 2012

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 ⇒ Object

Returns the string which represents the version of zlib library.



370
371
372
373
374
 
# File 'ext/zlib/zlib.c', line 370

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