Spec-Zone.ru › Ruby 2.6

модуль Zlib

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

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

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

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

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

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

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

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

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 дерево

  • Zlib::Deflate

  • Zlib::Inflate

  • Zlib::ZStream

  • Zlib::Error

    • Zlib::StreamEnd

    • Zlib::NeedDict

    • Zlib::DataError

    • Zlib::StreamError

    • Zlib::MemError

    • Zlib::BufError

    • Zlib::VersionError

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

  • Zlib::GzipReader

  • Zlib::GzipWriter

  • Zlib::GzipFile

  • Zlib::GzipFile::Error

    • Zlib::GzipFile::LengthError

    • Zlib::GzipFile::CRCError

    • Zlib::GzipFile::NoFooter

Константы

ASCII

Представляет текстовые данные, как предполагает deflate.

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

См. Zlib::Deflate#data_type.

НАИЛУЧШЕЕ_СЖАТИЕ

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

НАИЛУЧШАЯ_СКОРОСТЬ

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

ДВОИЧНЫЙ

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

См. Zlib::Deflate#data_type.

УСТАНОВЛЕННЫЙ_УРОВЕНЬ_СЖАТИЯ

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

УСТАНОВЛЕННАЯ_СТРАТЕГИЯ

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

УСТАНОВЛЕННЫЙ_УРОВЕНЬ_ПАМЯТИ

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

ФИЛЬТРОВАННЫЙ

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

ЗАВЕРШИТЬ

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

ФИКСИРОВАННЫЙ

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

ПОЛНАЯ_ОЧИСТКА

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

ТОЛЬКО_ХАФФМАН

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

МАКС_УРОВЕНЬ_ПАМЯТИ

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

МАКС_РАЗМЕР_БУФЕРА

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

БЕЗ_СЖАТИЯ

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

БЕЗ_ОЧИСТКИ

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

ОС_АМИГА

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

ОС_АТАРИ

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

КОД_ОС

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

ОС_КПМ

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

ОС_МАК

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

ОС_МSДОС

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

ОС_ОС2

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

ОС_КДОС

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

ОС_РИСКОС

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

ОС_ТОПС20

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

ОС_ЮНИКС

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

НЕИЗВЕСТНАЯ_ОС

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

ОС_ВМ

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

ОС_ВМС

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

ОС_ВИНДОУС32

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

ОС_ЗСИСТЕМА

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

RLE

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

СИНКРОННАЯ_ОЧИСТКА

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

ТЕКСТ

Представляет текстовые данные, как предполагает deflate.

См. Zlib::Deflate#data_type.

НЕИЗВЕСТНЫЙ

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

См. Zlib::Deflate#data_type.

ВЕРСИЯ

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

ВЕРСИЯ_ZLIB

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

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

adler32(строка, 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(строка, 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(строка[, уровень]) Показать исходный код
Zlib::Deflate.deflate(строка[, уровень])
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

См. также Zlib.inflate

gunzip(src) → Строка Показать исходный код
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);
}

Декодирует заданный сжатый string.

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

def gunzip(string)
  sio = StringIO.new(string)
  gz = Zlib::GzipReader.new(sio, encoding: Encoding::ASCII_8BIT)
  gz.read
ensure
  gz&.close
end

См. также Zlib.gzip

gzip(src, уровень: nil, стратегия: nil) → Строка Показать исходный код
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);
}

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

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

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

См. также Zlib.gunzip

inflate(строка) Показать исходный код
Zlib::Inflate.inflate(строка)
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

См. также Zlib.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.

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API