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)
- CLASS Zlib::BufError
- CLASS Zlib::DataError
- CLASS Zlib::Deflate
- CLASS Zlib::Error
- CLASS Zlib::GzipFile
- CLASS Zlib::GzipReader
- CLASS Zlib::GzipWriter
- CLASS Zlib::InProgressError
- CLASS Zlib::Inflate
- CLASS Zlib::MemError
- CLASS Zlib::NeedDict
- CLASS Zlib::StreamEnd
- CLASS Zlib::StreamError
- CLASS Zlib::VersionError
- CLASS Zlib::ZStream
- A
- C
- D
- G
- I
- Z
Constants
| ASCII | = | INT2FIX(Z_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 | = | INT2FIX(Z_BEST_COMPRESSION) |
Slowest compression level, but with the best space savings. |
||
| BEST_SPEED | = | INT2FIX(Z_BEST_SPEED) |
Fastest compression level, but with the lowest space savings. |
||
| BINARY | = | INT2FIX(Z_BINARY) |
Represents binary data as guessed by deflate. |
||
| DEFAULT_COMPRESSION | = | INT2FIX(Z_DEFAULT_COMPRESSION) |
Default compression level which is a good trade-off between space and time |
||
| DEFAULT_STRATEGY | = | INT2FIX(Z_DEFAULT_STRATEGY) |
Default deflate strategy which is used for normal data. |
||
| DEF_MEM_LEVEL | = | INT2FIX(DEF_MEM_LEVEL) |
The default memory level for allocating zlib deflate compression state. |
||
| FILTERED | = | INT2FIX(Z_FILTERED) |
|
||
| FINISH | = | INT2FIX(Z_FINISH) |
Processes all pending input and flushes pending output. |
||
| FIXED | = | INT2FIX(Z_FIXED) |
|
||
| FULL_FLUSH | = | INT2FIX(Z_FULL_FLUSH) |
Flushes all output as with |
||
| HUFFMAN_ONLY | = | INT2FIX(Z_HUFFMAN_ONLY) |
|
||
| MAX_MEM_LEVEL | = | INT2FIX(MAX_MEM_LEVEL) |
The maximum memory level for allocating zlib deflate compression state. |
||
| MAX_WBITS | = | INT2FIX(MAX_WBITS) |
The maximum size of the zlib history buffer. Note that zlib allows larger values to enable different inflate modes. See |
||
| NO_COMPRESSION | = | INT2FIX(Z_NO_COMPRESSION) |
No compression, passes through data untouched. Use this for appending pre-compressed data to a deflate stream. |
||
| NO_FLUSH | = | INT2FIX(Z_NO_FLUSH) |
|
||
| OS_AMIGA | = | INT2FIX(OS_AMIGA) |
OS code for Amiga hosts |
||
| OS_ATARI | = | INT2FIX(OS_ATARI) |
OS code for Atari hosts |
||
| OS_CODE | = | INT2FIX(OS_CODE) |
The OS code of current host |
||
| OS_CPM | = | INT2FIX(OS_CPM) |
OS code for CP/M hosts |
||
| OS_MACOS | = | INT2FIX(OS_MACOS) |
OS code for Mac OS hosts |
||
| OS_MSDOS | = | INT2FIX(OS_MSDOS) |
OS code for MSDOS hosts |
||
| OS_OS2 | = | INT2FIX(OS_OS2) |
OS code for OS2 hosts |
||
| OS_QDOS | = | INT2FIX(OS_QDOS) |
OS code for QDOS hosts |
||
| OS_RISCOS | = | INT2FIX(OS_RISCOS) |
OS code for RISC OS hosts |
||
| OS_TOPS20 | = | INT2FIX(OS_TOPS20) |
OS code for TOPS-20 hosts |
||
| OS_UNIX | = | INT2FIX(OS_UNIX) |
OS code for UNIX hosts |
||
| OS_UNKNOWN | = | INT2FIX(OS_UNKNOWN) |
OS code for unknown hosts |
||
| OS_VMCMS | = | INT2FIX(OS_VMCMS) |
OS code for VM OS hosts |
||
| OS_VMS | = | INT2FIX(OS_VMS) |
OS code for VMS hosts |
||
| OS_WIN32 | = | INT2FIX(OS_WIN32) |
OS code for |
||
| OS_ZSYSTEM | = | INT2FIX(OS_ZSYSTEM) |
OS code for Z-System hosts |
||
| RLE | = | INT2FIX(Z_RLE) |
|
||
| SYNC_FLUSH | = | INT2FIX(Z_SYNC_FLUSH) |
The |
||
| TEXT | = | INT2FIX(Z_TEXT) |
Represents text data as guessed by deflate. |
||
| UNKNOWN | = | INT2FIX(Z_UNKNOWN) |
Represents an unknown data type as guessed by deflate. |
||
| VERSION | = | rb_str_new2(RUBY_ZLIB_VERSION) |
The Ruby/zlib version string. |
||
| ZLIB_VERSION | = | rb_str_new2(ZLIB_VERSION) |
The string which represents the version of zlib.h |
||
Class Public methods
Zlib.adler32(string, adler) Link
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
Source: show
static VALUE
rb_zlib_adler32(int argc, VALUE *argv, VALUE klass)
{
return do_checksum(argc, argv, adler32);
}
Zlib.adler32_combine(adler1, adler2, len2) Link
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.
Source: show
static VALUE
rb_zlib_adler32_combine(VALUE klass, VALUE adler1, VALUE adler2, VALUE len2)
{
return ULONG2NUM(
adler32_combine(NUM2ULONG(adler1), NUM2ULONG(adler2), NUM2LONG(len2)));
}
Zlib.crc32(string, crc) Link
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.
Source: show
static VALUE
rb_zlib_crc32(int argc, VALUE *argv, VALUE klass)
{
return do_checksum(argc, argv, crc32);
}
Zlib.crc32_combine(crc1, crc2, len2) Link
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.
Source: show
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() Link
Returns the table for calculating CRC checksum as an array.
Source: show
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;
}
Zlib.deflate(string[, level])
Zlib::Deflate.deflate(string[, level])
Link
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
Source: show
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;
}
Zlib.gunzip(src) → String Link
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
Source: show
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);
}
Zlib.gzip(src, level: nil, strategy: nil) → String Link
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
Source: show
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);
}
Zlib.inflate(string)
Zlib::Inflate.inflate(string)
Link
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
Source: show
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;
}