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