модуль 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 дерево
(если у вас есть GZIP_SUPPORT)
Константы
- ASCII
-
Представляет текстовые данные, как предполагается deflate.
ПРИМЕЧАНИЕ: Базовая константа Z_ASCII была устарела в пользу Z_TEXT в zlib 1.2.2. Новые приложения не должны использовать эту константу.
- BEST_COMPRESSION
-
Самый медленный уровень сжатия, но с лучшей экономией места.
- BEST_SPEED
-
Самый быстрый уровень сжатия, но с наименьшей экономией места.
- BINARY
-
Представляет бинарные данные, как предполагается deflate.
- DEFAULT_COMPRESSION
-
Уровень сжатия по умолчанию, являющийся хорошим компромиссом между объемом и временем.
- DEFAULT_STRATEGY
-
Стратегия deflate по умолчанию, используемая для обычных данных.
- DEF_MEM_LEVEL
-
Уровень памяти по умолчанию для выделения состояния сжатия zlib deflate.
- FILTERED
-
Стратегия
Deflateдля данных, полученных от фильтра (или предиктора). ВлияниеFILTEREDзаключается в принудительном использовании большего количества кодов Хаффмана и меньшего количества сопоставлений строк; это несколько промежуточно междуDEFAULT_STRATEGYиHUFFMAN_ONLY. Отфильтрованные данные состоят в основном из малых значений с несколько случайным распределением. - FINISH
-
Обрабатывает все ожидающие входные данные и сбрасывает ожидающие выходные данные.
- FIXED
-
Стратегия
Deflate, которая предотвращает использование динамических кодов Хаффмана, что позволяет использовать более простой декодер для специализированных приложений. - FULL_FLUSH
-
Сбрасывает все выходные данные, как при
SYNC_FLUSH, и состояние сжатия сбрасывается, так что распаковка может перезапуститься с этой точки, если предыдущие сжатые данные были повреждены или если требуется произвольный доступ. Как и приSYNC_FLUSH, чрезмерное использованиеFULL_FLUSHможет серьезно ухудшить сжатие. - HUFFMAN_ONLY
-
Стратегия
Deflate, которая использует только коды Хаффмана (без сопоставления строк). - MAX_MEM_LEVEL
-
Максимальный уровень памяти для выделения состояния сжатия zlib deflate.
- 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.
- UNKNOWN
-
Представляет неизвестный тип данных, как предполагается deflate.
- VERSION
-
Строка версии Ruby/zlib.
- ZLIB_VERSION
-
Строка, представляющая версию zlib.h.
Методы публичного класса
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
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.
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: выражение.
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.
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 в виде массива.
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
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
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 в формате gzip. Допустимые значения уровня: 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
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
static VALUE
rb_zlib_version(VALUE klass)
{
return rb_str_new2(zlibVersion());
} Возвращает строку, представляющую версию библиотеки zlib.
Ruby Core © 1993–2020 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.