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¶ ↑
(if you have GZIP_SUPPORT)
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.
- 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.
- 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.
- UNKNOWN
Represents an unknown data type as guessed by deflate.
- VERSION
The Ruby/zlib version string.
- ZLIB_VERSION
The string which represents the version of zlib.h
Public Class Methods
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.
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);
}
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.
static VALUE
rb_zlib_adler32_combine(VALUE klass, VALUE adler1, VALUE adler2, VALUE len2)
{
return ULONG2NUM(
adler32_combine(NUM2ULONG(adler1), NUM2ULONG(adler2), NUM2LONG(len2)));
}
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.
FIXME: expression.
static VALUE
rb_zlib_crc32(int argc, VALUE *argv, VALUE klass)
{
return do_checksum(argc, argv, crc32);
}
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)));
}
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;
}
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 ::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_end, (VALUE)&z);
OBJ_INFECT(dst, src);
return dst;
}
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
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 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 ::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);
}
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 ::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_end, (VALUE)&z);
OBJ_INFECT(dst, src);
return dst;
}
Returns the string which represents the version of zlib library.
static VALUE
rb_zlib_version(VALUE klass)
{
VALUE str;
str = rb_str_new2(zlibVersion());
OBJ_TAINT(str); /* for safe */
return str;
}