Spec-Zone.ru › Ruby 3.4

модуль 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(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);
}

Декодирует сжатый gzip 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, level: nil, strategy: 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–2024 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.

Spec-Zone.ru

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