модуль Zlib

Этот модуль предоставляет доступ к библиотеке zlib. Zlib разработан как портабельная, бесплатная, универсальная, не лицензируемая по патентам — то есть не защищённая никакими патентами — библиотека для сжатия без потерь данных, пригодная для использования практически на любом компьютерном оборудовании и операционной системе.

Библиотека сжатия zlib предоставляет функции сжатия и распаковки данных в памяти, включая проверки целостности несжатых данных.

Формат сжатых данных zlib описан в RFC 1950, который является оболочкой над потоком deflate, описанным в RFC 1951.

Библиотека также поддерживает чтение и запись файлов в формате gzip (.gz) с интерфейсом, похожим на интерфейс IO. Формат gzip описан в RFC 1952, который также является оболочкой над потоком deflate.

Формат zlib разработан для компактности и скорости использования в памяти и на каналах связи. Формат gzip разработан для сжатия отдельных файлов на файловых системах, имеет более крупный заголовок, чем zlib, для сохранения информации о каталоге, и использует другой, более медленный метод проверки, чем zlib.

Для получения дополнительной информации о zlib см. zlib.h на вашей системе.

Пример использования

Использование оболочки для сжатия строк с параметрами по умолчанию довольно просто:

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

Дерево классов

(если у вас есть GZIP_SUPPORT)

Константы

ASCII

Представляет текстовые данные, как предполагается по умолчанию в deflate.

ПРИМЕЧАНИЕ: Встроенная константа Z_ASCII была устарела в пользу Z_TEXT в zlib 1.2.2. Новые приложения не должны использовать эту константу.

См. Zlib::ZStream#data_type.

BEST_COMPRESSION

Самый медленный уровень сжатия, но с наилучшим экономией места.

BEST_SPEED

Самый быстрый уровень сжатия, но с наименьшей экономией места.

BINARY

Представляет двоичные данные, как предполагается по умолчанию в deflate.

См. Zlib::ZStream#data_type.

DEFAULT_COMPRESSION

Уровень сжатия по умолчанию, который представляет собой хороший компромисс между размером и временем.

DEFAULT_STRATEGY

Стратегия deflate по умолчанию, которая используется для обычных данных.

DEF_MEM_LEVEL

Уровень памяти по умолчанию для выделения состояния сжатия deflate zlib.

FILTERED

Стратегия Deflate для данных, сгенерированных фильтром (или предиктором). Эффект FILTERED заключается в принудительном использовании большего количества кодов Хаффмана и меньшего количества сопоставлений строк; он находится где-то между DEFAULT_STRATEGY и HUFFMAN_ONLY. Отфильтрованные данные в основном состоят из малых значений с несколько случайным распределением.

FINISH

Обрабатывает все ожидающие входные данные и сбрасывает ожидающие выходные данные.

FIXED

Стратегия Deflate, которая предотвращает использование динамических кодов Хаффмана, что позволяет упростить декодер для специализированных приложений.

FULL_FLUSH

Сбрасывает все выходные данные, как и SYNC_FLUSH, и состояние сжатия сбрасывается, так что декомпрессия может возобновиться с этой точки, если предыдущие сжатые данные повреждены или если требуется произвольный доступ. Как и SYNC_FLUSH, слишком частое использование FULL_FLUSH может существенно ухудшить сжатие.

HUFFMAN_ONLY

Стратегия Deflate, которая использует только коды Хаффмана (без сопоставления строк).

MAX_MEM_LEVEL

Максимальный уровень памяти для выделения состояния сжатия deflate zlib.

MAX_WBITS

Максимальный размер буфера истории zlib. Обратите внимание, что zlib допускает большие значения для включения различных режимов inflate. См. Zlib::Inflate.new для получения подробностей.

NO_COMPRESSION

Без сжатия, данные проходят без изменений. Используйте это для добавления предварительно сжатых данных в поток deflate.

NO_FLUSH

NO_FLUSH — это метод сброса по умолчанию, который позволяет deflate решать, сколько данных накапливать перед производством выходных данных, чтобы максимизировать сжатие.

OS_AMIGA

Код ОС для хостов Amiga

OS_ATARI

Код ОС для хостов Atari

OS_CODE

Код ОС текущего хоста

OS_CPM

Код ОС для хостов CP/M

OS_MACOS

Код ОС для хостов Mac OS

OS_MSDOS

Код ОС для хостов MSDOS

OS_OS2

Код ОС для хостов OS2

OS_QDOS

Код ОС для хостов QDOS

OS_RISCOS

Код ОС для хостов RISC OS

OS_TOPS20

Код ОС для хостов TOPS-20

OS_UNIX

Код ОС для хостов UNIX

OS_UNKNOWN

Код ОС для неизвестных хостов

OS_VMCMS

Код ОС для хостов VM OS

OS_VMS

Код ОС для хостов VMS

OS_WIN32

Код ОС для хостов Win32

OS_ZSYSTEM

Код ОС для хостов Z-System

RLE

Стратегия сжатия Deflate, разработанная для обеспечения практически такой же скорости, как HUFFMAN_ONLY, но с лучшим сжатием данных изображений PNG.

SYNC_FLUSH

Метод SYNC_FLUSH сбрасывает все ожидающие выходные данные в буфер вывода, и выход выравнивается на границе байта. Сброс может ухудшить сжатие, поэтому его следует использовать только при необходимости, например, на границе запроса или ответа для сетевого потока.

TEXT

Представляет текстовые данные, как предполагается по умолчанию в deflate.

См. Zlib::ZStream#data_type.

UNKNOWN

Представляет неизвестный тип данных, как предполагается по умолчанию в deflate.

См. Zlib::ZStream#data_type.

VERSION

Строка версии Ruby/zlib.

ZLIB_VERSION

Строка, представляющая версию zlib.h

Методы публичного класса

adler32(string, adler) Показать исходный код

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

Вычисляет контрольную сумму Adler-32 для string, и возвращает обновлённое значение adler. Если string опущено, возвращается начальное значение Adler-32. Если adler опущено, предполагается, что начальное значение передаётся adler.

Пример использования:

require "zlib"

data = "foo"
puts "Adler32 checksum: #{Zlib.adler32(data).to_s(16)}"
#=> Adler32 checksum: 2820145

adler32_combine(adler1, adler2, len2) Показать исходный код

static VALUE
rb_zlib_adler32_combine(VALUE klass, VALUE adler1, VALUE adler2, VALUE len2)
{
  return ULONG2NUM(
        adler32_combine(NUM2ULONG(adler1), NUM2ULONG(adler2), NUM2LONG(len2)));
}

Объединяет два значения контрольной суммы Adler-32 в одно. alder1 — первое значение Adler-32, adler2 — второе значение Adler-32. len2 — длина строки, используемой для генерации adler2.

crc32(string, crc) Показать исходный код

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

Вычисляет контрольную сумму CRC для string, и возвращает обновлённое значение crc. Если string опущено, возвращается начальное значение CRC. Если crc опущено, предполагается, что начальное значение передаётся crc.

FIXME: выражение.

crc32_combine(crc1, crc2, len2) Показать исходный код

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-32 в одно. crc1 — первое значение CRC-32, crc2 — второе значение CRC-32. len2 — длина строки, используемой для генерации crc2.

crc_table() Показать исходный код

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

Возвращает таблицу для вычисления контрольной суммы CRC в виде массива.

deflate(string[, level]) Показать исходный код

Zlib::Deflate.deflate(string[, level])

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

Сжимает заданную string. Допустимые значения уровня — Zlib::NO_COMPRESSION, Zlib::BEST_SPEED, Zlib::BEST_COMPRESSION, Zlib::DEFAULT_COMPRESSION или целое число от 0 до 9.

Этот метод почти эквивалентен следующему коду:

def deflate(string, level)
  z = Zlib::Deflate.new(level)
  dst = z.deflate(string, Zlib::FINISH)
  z.close
  dst
end

См. также ::inflate

inflate(string) Показать исходный код

Zlib::Inflate.inflate(string)

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

Декомпримирует string. Вызывает исключение Zlib::NeedDict, если для декомпрессии требуется предварительно заданный словарь.

Этот метод почти эквивалентен следующему коду:

def inflate(string)
  zstream = Zlib::Inflate.new
  buf = zstream.inflate(string)
  zstream.finish
  zstream.close
  buf
end

См. также ::deflate

zlib_version() Показать исходный код

static VALUE
rb_zlib_version(VALUE klass)
{
    VALUE str;

    str = rb_str_new2(zlibVersion());
    OBJ_TAINT(str);  /* for safe */
    return str;
}

Возвращает строку, представляющую версию библиотеки zlib.

Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.