Spec-Zone.ru › Ruby 3.2

модуль 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...

Class дерево

  • Zlib::Deflate

  • Zlib::Inflate

  • Zlib::ZStream

  • Zlib::Error

    • Zlib::StreamEnd

    • Zlib::NeedDict

    • Zlib::DataError

    • Zlib::StreamError

    • Zlib::MemError

    • Zlib::BufError

    • Zlib::VersionError

    • Zlib::InProgressError

(если у вас есть 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.

BEST_COMPRESSION

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

BEST_SPEED

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

BINARY

Представляет бинарные данные, угаданные deflate.

См. Zlib::Deflate#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 позволяет использовать более высокие значения для активации различных режимов распаковки. Подробности см. в 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::Deflate#data_type.

UNKNOWN

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

См. Zlib::Deflate#data_type.

VERSION

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

ZLIB_VERSION

Строка, представляющая версию 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. Если string является экземпляром IO, считывает данные из IO до тех пор, пока IO не вернёт nil, и возвращает контрольную сумму Adler-32 для всех прочитанных данных.

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

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 в одну. adler1 — первое значение контрольной суммы 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. Если string является экземпляром IO, считывает данные из IO до тех пор, пока IO не вернёт nil, и возвращает контрольную сумму 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_ensure_end, (VALUE)&z);

    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(источник) → Строка Показать исходный код
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(источник, уровень: 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_ensure_end, (VALUE)&z);

    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)
{
    return rb_str_new2(zlibVersion());
}

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

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

Spec-Zone.ru

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