zlib

Команда zlib предоставляет доступ к функциям сжатия и вычисления контрольных сумм библиотеки Zlib, разработанной Jean-loup Gailly и Mark Adler. Она имеет следующие подкоманды.

Подкоманды сжатия

zlib compress строка ?уровень?

Возвращает сжатые в формате zlib бинарные данные бинарной строки в строке. Если присутствует, уровень задаёт уровень сжатия (от 0, не сжато, до 9, максимальное сжатие).

zlib decompress строка ?размерБуфера?

Возвращает не сжатую версию исходных сжатых бинарных данных в строке. Если присутствует, размерБуфера указывает предполагаемый размер буфера для получения данных.

zlib deflate строка ?уровень?

Возвращает сжатые в сыром формате бинарные данные бинарной строки в строке. Если присутствует, уровень задаёт уровень сжатия (от 0, не сжато, до 9, максимальное сжатие).

zlib gunzip строка ?-headerVar имяПеременной?

Возвращает не сжатое содержимое бинарной строки строка, которая должна быть в формате gzip. Если задан параметр -headerVar, в переменную с именем имяПеременной записывается словарь, описывающий содержимое заголовка gzip. Ключами словаря, которые могут присутствовать, являются:

comment: Поле комментария из заголовка, если оно есть.
crc: Булево значение, указывающее, вычисляется ли CRC заголовка.
filename: Поле имени файла из заголовка, если оно есть.
os: Код типа операционной системы из заголовка (если не QW неизвестное значение). Значения кодов см. в RFC 1952.
size: Размер не сжатых данных.
time: Поле времени из заголовка, если оно не равно нулю, ожидается, что оно соответствует времени последней модификации файла, указанного в поле filename. Подходит для использования с форматом времени.
type: Тип несжатых данных (binary или text), если известен.

zlib gzip строка ?-level уровень? ?-header словарь?

Возвращает сжатое содержимое бинарной строки строка в формате gzip. Если задан параметр -level, уровень задаёт уровень сжатия (от 0, не сжато, до 9, максимальное сжатие). Если задан параметр -header, словарь содержит значения, используемые для заголовка gzip. Следующие ключи могут быть определены:

comment: Добавляет заданный комментарий в заголовок данных в формате gzip.
crc: Булево значение, указывающее, вычисляется ли CRC заголовка. Обратите внимание, что если данные обмениваются с программой gzip, CRC заголовка не должен вычисляться.
filename: Имя файла, из которого были взяты данные для сжатия.
os: Код типа операционной системы, который должен быть одним из значений, описанных в RFC 1952.
time: Время последней модификации файла, имя которого указано в ключе filename. Время будет в том же формате, что и возвращаемое значение clock seconds или file mtime.
type: Тип сжимаемых данных, binary или text.

zlib inflate строка ?размерБуфера?

Подкоманда канала

zlib push mode channel ?options ...?

Нажимает преобразование сжатия или распаковки на канал channel. Преобразование можно снова удалить с помощью chan pop. Аргумент mode определяет тип преобразования; поддерживаются следующие:

compress: Преобразование будет преобразованием сжатия, которое создаёт данные в формате zlib на канале channel, который должен быть доступен для записи.
decompress: Преобразование будет преобразованием распаковки, которое считывает данные в формате zlib из канала channel, который должен быть доступен для чтения.
deflate: Преобразование будет преобразованием сжатия, которое создаёт сырые сжатые данные на канале channel, который должен быть доступен для записи.
gunzip: Преобразование будет преобразованием распаковки, которое считывает данные в формате gzip из канала channel, который должен быть доступен для чтения.
gzip: Преобразование будет преобразованием сжатия, которое создаёт данные в формате gzip на канале channel, который должен быть доступен для записи.
inflate: Преобразование будет преобразованием распаковки, которое считывает сырые сжатые данные из канала channel, который должен быть доступен для чтения.

При создании преобразования с помощью команд «options ...» к команде zlib push можно задать следующие параметры:

-dictionary binData: Устанавливает словарь сжатия для работы со сжатием или распаковкой данных на binData. Недействительно для преобразований, работающих с данными в формате gzip. Словарь должен состоять из строк (последовательностей байтов), которые, скорее всего, встретятся позже в сжимаемых данных, причём наиболее часто используемые строки желательно поместить в конец словаря. Tcl не предоставляет механизма для выбора хорошего словаря для конкретной последовательности данных.
-header dictionary: Передаёт описание заголовка gzip для создания в том же формате, что и команда zlib gzip.
-level compressionLevel: Как сильно сжимать данные. Должно быть целым числом от 0 (не сжато) до 9 (максимально сжато).
-limit readaheadLimit: Максимальное количество байтов вперёд для чтения при распаковке. По умолчанию значение равно 1, что гарантирует правильное распаковку данных, но может быть увеличено для повышения производительности. Это более полезно, когда канал неблокирующий.

Преобразования каналов сжатия и распаковки добавляют дополнительные параметры конфигурации, к которым можно получить доступ через chan configure. Параметры:

-checksum checksum: Этот только для чтения параметр получает текущую контрольную сумму несжатых данных, которые видел двигатель сжатия до сих пор. Действителен как для сжимающих, так и для распаковывающих преобразований, но не для сырых форматов inflate и deflate. Алгоритм сжатия зависит от того, какой формат создаётся или потребляется.
-dictionary binData: Этот параметр для чтения и записи получает или устанавливает начальный словарь сжатия для работы со сжатием или распаковкой данных на binData. Недействителен для преобразований, работающих с данными в формате gzip, и обычно не должен устанавливаться для сжимающих преобразований, кроме как в момент, когда преобразование стекируется. Обратите внимание, что это нельзя использовать для получения текущего активного словаря сжатия в процессе, так как эта информация не предоставляется основной библиотекой.
-flush type: Эта операция только для записи сбрасывает текущее состояние компрессора в подлежащий канал. Действительно только для сжимающих преобразований. type должен быть либо sync, либо full для нормального сброса или дорогостоящего сброса, соответственно. Сброс ухудшает коэффициент сжатия, но упрощает декомпрессору восстановить больше файла в случае повреждения данных.
-header dictionary: Этот только для чтения параметр, действительный только для распаковывающих преобразований, обрабатывающих данные в формате gzip, возвращает словарь, описывающий прочитанный заголовок из потока данных.
-limit readaheadLimit: Этот параметр для чтения и записи используется распаковывающими каналами для управления максимальным количеством байтов вперёд для чтения из исходного источника данных. По умолчанию значение равно 1, что гарантирует правильное распаковку данных, но может быть увеличено для повышения производительности. Это более полезно, когда канал неблокирующий.

Команда подпотока

zlib stream mode ?options?

Создаёт команду потокового сжатия или распаковки на основе mode и возвращает имя команды. Для описания работы этой команды см. КОМАНДА ИНСТАНЦИИ ПОТОКА ниже. Поддерживаются следующие режимы и options:

zlib stream compress ?-dictionary bindata? ?-level level?: Поток будет потоком сжатия, который генерирует выходные данные в формате zlib, используя уровень сжатия level (если указан), который будет целым числом от 0 до 9, и словарь сжатия bindata (если указан).
zlib stream decompress ?-dictionary bindata?: Поток будет потоком распаковки, который принимает входные данные в формате zlib и генерирует несжатые выходные данные. Если указано bindata, это словарь сжатия, который будет использоваться при необходимости.
zlib stream deflate ?-dictionary bindata? ?-level level?: Поток будет потоком сжатия, который генерирует сырые выходные данные, используя уровень сжатия level (если указан), который будет целым числом от 0 до 9, и словарь сжатия bindata (если указан). Обратите внимание, что сырые сжатые данные не содержат метаданных о том, какой словарь сжатия использовался, если таковой был; это особенность данных в формате zlib.
zlib stream gunzip: Поток будет потоком распаковки, который принимает входные данные в формате gzip и генерирует несжатые выходные данные.
zlib stream gzip ?-header header? ?-level level?: Поток будет потоком сжатия, который генерирует выходные данные в формате gzip, используя уровень сжатия level (если указан), который будет целым числом от 0 до 9, и описатель заголовка словаря header (если указан; для ключей см. zlib gzip).
zlib stream inflate ?-dictionary bindata?: Поток будет потоком распаковки, который принимает сырые сжатые входные данные и генерирует несжатые выходные данные. Если указано bindata, это словарь сжатия, который будет использоваться. Обратите внимание, что нет проверок, чтобы определить, является ли словарь сжатия правильным.

Команды проверки контрольных сумм

zlib adler32 string ?initValue?: Вычислить контрольную сумму бинарной строки string с помощью алгоритма Adler-32. Если задано, initValue используется для инициализации двигателя контрольной суммы.
zlib crc32 string ?initValue?: Вычислить контрольную сумму бинарной строки string с помощью алгоритма CRC-32. Если задано, initValue используется для инициализации двигателя контрольной суммы.

Команда экземпляра потока

Команды экземпляров потокового сжатия создаются командой zlib stream. Они используются, вызывая их подкоманду put один или несколько раз для загрузки данных, и их подкоманду get один или несколько раз для извлечения преобразованных данных.

Полный набор подкоманд, поддерживаемых командой экземпляра потока, stream, выглядит следующим образом:

stream add ?option...? data

Быстрый способ выполнить «stream put ?option...? data» за которым следует «stream get».

stream checksum

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

stream close

Удаляет этот поток и освобождает все ресурсы, связанные с ним.

stream eof

Возвращает логическое значение, указывающее, достигнут ли конец потока (как определено самими сжатыми данными). Не все форматы поддерживают определение конца потока.

stream finalize

Быстрый способ для «stream put -finalize {}».

stream flush

Быстрый способ для «stream put -flush {}».

stream fullflush

Быстрый способ для «stream put -fullflush {}».

stream get ?count?

Возвращает до count байтов из внутренних буферов stream с применённым преобразованием. Если count опущено, возвращаются все содержимое буферов. stream header Возвращает словарь описания заголовка gzip, извлечённый из потока. Поддерживается только для потоков, созданных с параметром mode, установленным в gunzip.

stream put ?option...? data

Добавляет содержимое двоичной строки data к внутренним буферам stream, применяя преобразование. Поддерживаются следующие опции (или их недвусмысленные префиксы), которые используются для изменения способа применения преобразования:

-dictionary binData: Устанавливает словарь сжатия, используемый при работе со сжатием или распаковкой данных, на binData.
-finalize: Помечает поток как завершённый, гарантируя, что все байты были полностью сжаты или распакованы. Для потоков gzip это также гарантирует, что футер записан в поток. Поток потребуется сбросить, прежде чем писать в него дополнительные данные после этого, хотя данные всё ещё можно считать из потока с помощью подкоманды get.
Эта опция взаимоисключающая с опциями -flush и -fullflush.
-flush: Гарантирует, что декомпрессор, потребляющий байты, которые производит текущий (сжимающий) поток, сможет произвести все сжатые байты до этого момента, с некоторыми потерями производительности.
Эта опция взаимоисключающая с опциями -finalize и -fullflush.
-fullflush: Гарантирует, что декомпрессор не только может обработать все произведённые байты (как с -flush выше), но и может перезапуститься с этой точки, если обнаружит, что поток частично повреждён. Это влечёт существенные потери производительности.
Эта опция взаимоисключающая с опциями -finalize и -flush.

stream reset

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

Примеры

Для сжатия строки Tcl, она должна быть сначала преобразована в кодировку символов, так как команда zlib всегда работает с двоичными строками.

set binData [encoding convertto utf-8 $string]
set compData [zlib compress $binData]

При обратном преобразовании также важно выполнить обратное преобразование кодировки символов:

set binData [zlib decompress $compData]
set string [encoding convertfrom utf-8 $binData]

Операция сжатия, описанная выше, также может быть выполнена с помощью потоков, что особенно полезно, когда вы хотите накапливать данные поэтапно:

set strm [zlib stream compress]
$strm put [encoding convertto utf-8 $string]
# ...
$strm finalize
set compData [$strm get]
$strm close

См. также

binary, chan, encoding, Tcl_ZlibDeflate, RFC1950 - RFC1952

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TclCmd/zlib.htm