zlib
zlib
模块
zlib
模块摘要
zlib压缩接口
描述
该模块为zlib库（www.zlib.net）提供了一个API 。它用于压缩和解压缩数据。的数据格式由描述RFC 1950，RFC 1951和RFC 1952。
典型的（压缩）用法如下：
Z = zlib:open(),
ok = zlib:deflateInit(Z,default),
Compress = fun(end_of_data, _Cont) -> [];
(Data, Cont) ->
[zlib:deflate(Z, Data)|Cont(Read(),Cont)]
end,
Compressed = Compress(Read(),Compress),
Last = zlib:deflate(Z, [], finish),
ok = zlib:deflateEnd(Z),
zlib:close(Z),
list_to_binary([Compressed|Last])
在所有函数错误中{'EXIT',{Reason,Backtrace}}，都可以抛出，Reason描述错误的地方。
典型Reasonss：
badarg错误的论据。not_initialized流尚未初始化，例如。如果inflateInit/1在呼叫之前未被呼叫inflate/2。data_error数据包含错误。stream_error流状态不一致。{need_dictionary,Adler32}看inflate/2。
数据类型
zstream() = term()
一个zlib流，见open/0。
zlevel() =
none | default | best_compression | best_speed | 0..9
zflush() = none | sync | full | finish
zmemlevel() = 1..9
zmethod() = deflated
zstrategy() = default | filtered | huffman_only | rle
zwindowbits() = -15..-8 | 8..47
通常在范围内-15..-8 | 8..15。
出口
adler32(Z, Data) -> CheckSum
类型
计算Adler-32校验和Data。
警告
此功能已弃用，将在未来版本中删除。erlang:adler32/1改为使用。
adler32(Z, PrevAdler, Data) -> CheckSum
类型
更新正在运行的Adler-32校验和Data。如果Data是空的二进制文件或空的iolist，则此函数会返回校验和所需的初始值。
例子：
Crc = lists:foldl(fun(Data,Crc0) ->
zlib:adler32(Z, Crc0, Data),
end, zlib:adler32(Z,<< >>), Datas)
警告
此功能已弃用，将在未来版本中删除。erlang:adler32/2改为使用。
adler32_combine(Z, Adler1, Adler2, Size2) -> Adler
类型
将两个Adler-32校验和合并成一个。对于两个二进制文件或iolists，Data1并且Data2大小为Size1和Size2，使用Adler-32校验Adler1和和Adler2。
该函数返回Adler的校验和[Data1,Data2]，只需要Adler1，Adler2和Size2。
警告
此功能已弃用，将在未来版本中删除。erlang:adler32_combine/3改为使用。
close(Z) -> ok
类型
关闭由引用的流Z。
compress(Data) -> Compressed
类型
用zlib头和校验和压缩数据。
crc32(Z) -> CRC
类型
获取当前计算的CRC校验和。
警告
此功能已弃用，将在未来版本中删除。改用erlang:crc32/1未压缩的数据。
crc32(Z, Data) -> CRC
类型
计算CRC校验和Data。
警告
此功能已弃用，将在未来版本中删除。erlang:crc32/1改为使用。
crc32(Z, PrevCRC, Data) -> CRC
类型
更新正在运行的CRC校验和Data。如果Data是空的二进制或空的iolist，则此函数返回CRC所需的初始值。
例子：
Crc = lists:foldl(fun(Data,Crc0) ->
zlib:crc32(Z, Crc0, Data),
end, zlib:crc32(Z,<< >>), Datas)
警告
此功能已弃用，将在未来版本中删除。erlang:crc32/2改为使用。
crc32_combine(Z, CRC1, CRC2, Size2) -> CRC
类型
将两个CRC校验和合并成一个。对于两个二进制文件或iolists，Data1并Data2与大小Size1和Size2，与CRC校验CRC1和CRC2。
该函数返回CRC的校验和[Data1,Data2]，只需要CRC1，CRC2和Size2。
警告
此功能已弃用，将在未来版本中删除。erlang:crc32_combine/3改为使用。
deflate(Z, Data) -> Compressed
类型
和...一样deflate(Z, Data, none)。
deflate(Z, Data, Flush) -> Compressed
类型
压缩尽可能多的数据，并在输入缓冲区变空时停止。它可以引入一些输出延迟（读输入不产生任何输出），除非强制刷新。
如果Flush设置为sync，则所有待处理的输出都刷新到输出缓冲区，并且输出在字节边界上对齐，以便解压缩程序可以获取到目前为止所有可用的输入数据。冲洗会降低某些压缩算法的压缩率; 因此，只有在必要时才使用它。
如果Flush设置为full，则所有输出都会刷新sync，并且压缩状态将重置，以便如果先前的压缩数据已损坏或需要随机访问，解压缩可从此位置重新开始。full过度使用会严重降低压缩。
如果Flush设置为finish，待处理的输入被处理，待处理的输出被刷新并deflate/3返回。之后，流中唯一可能的操作是deflateReset/1或deflateEnd/1。
Flush如果要在一个步骤中完成所有压缩，可以finish立即设置deflateInit。
例子：
zlib:deflateInit(Z),
B1 = zlib:deflate(Z,Data),
B2 = zlib:deflate(Z,<< >>,finish),
zlib:deflateEnd(Z),
list_to_binary([B1,B2])
deflateEnd(Z) -> ok
类型
结束放气会话并清理所有使用的数据。注意，data_error如果最后一次调用deflate/3未被Flush设置为未调用，则此函数会引发异常finish。
deflateInit(Z) -> ok
类型
和zlib:deflateInit(Z, default)一样。
deflateInit(Z, Level) -> ok
类型
初始化zlib流以进行压缩。
Level决定要使用的压缩级别：
- 0（
none）不提供压缩
- 1（
best_speed）提供最佳速度
- 9（
best_compression）给出最佳压缩
deflateInit（Z，Level，Method，WindowBits，MemLevel，Strategy） - >
好的
类型
启动用于压缩的zlib流。
Level
要使用的压缩级别：
- 0（
none）不提供压缩
- 1（
best_speed）提供最佳速度
- 9（
best_compression）给出最佳压缩
Method
要使用压缩方法，目前唯一支持的方法是deflated。
WindowBits
基本的窗口大小的两倍对数（历史缓冲区的大小）。它应该在8到15的范围内。较大的值会导致更好的压缩，但会占用内存。如果deflateInit/2使用，则默认为15 。负值将WindowBits抑制流中的zlib标题（和校验和）。请注意，zlib源只提到这是一个未记录的功能。
警告
由于底层zlib库中存在已知错误，因此WindowBits值8和-8不能按预期工作。在1.2.9之前的zlib版本中，值8和-8会自动更改为9和-9。从zlib版本1.2.9中，值-8被拒绝导致zlib:deflateInit/6失败（8仍然更改为9）。未来版本的zlib似乎也可能修复这个bug并开始接受8和-8。
结论：除非您知道您的zlib版本支持它们，否则请避免使用值8和-8。
MemLevel
指定为内部压缩状态分配多少内存：MemLevel= 1使用最小内存，但速度较慢并且压缩比降低; MemLevel= 9使用最大内存以获得最佳速度。默认为8。
Strategy
调整压缩算法。使用下列值：
default用于正常数据
filtered对于过滤器（或预测器）产生的数据，
huffman_only仅强制霍夫曼编码（无字符串匹配）
rle将匹配距离限制为一个（游程长度编码）
经过滤的数据主要由小的值组成，并且分布有些随机。在这种情况下，压缩算法被调整以更好地压缩它们。其效果filtered是强制更多的霍夫曼编码和更少的字符串匹配; 它default和之间有点中间huffman_only。rle被设计为几乎一样快huffman_only，但是为PNG图像数据提供更好的压缩。
Strategy 只影响压缩率，但不影响压缩输出的正确性，即使它没有适当设置。
deflateParams(Z, Level, Strategy) -> ok
类型
动态更新压缩级别和压缩策略。解释Level和Strategy如在deflateInit/6。这可以用来在输入数据的压缩和直接复制之间切换，或切换到需要不同策略的不同类型的输入数据。如果压缩级别被改变，那么到目前为止可用的输入被压缩到旧级别（并且可以被刷新）。新的级别仅在下次调用时生效deflate/3。
在调用之前deflateParams，流状态必须设置为调用deflate/3，因为当前可用的输入可能必须被压缩和刷新。
deflateReset(Z) -> ok
类型
等同于deflateEnd/1后面deflateInit/1,2,6，但不释放并重新分配所有内部压缩状态。该流保持相同的压缩级别和任何其他属性。
deflateSetDictionary(Z, Dictionary) -> Adler32
类型
从指定的字节序列初始化压缩字典，不产生任何压缩输出。
该功能后必须立即叫deflateInit/1,2,6或者deflateReset/1，任何调用之前deflate/3。
压缩器和解压缩器必须使用相同的字典（请参阅inflateSetDictionary/2）。
返回字典的Adler校验和。
getBufSize（Z） - > integer（）> = 0
类型
获取中间缓冲区的大小。
警告
此函数已被取消，并将在以后的版本中删除。
gunzip(Data) -> Decompressed
类型
用GZ头和校验和解压缩数据。
gzip(Data) -> Compressed
类型
使用GZ头和校验和压缩数据。
inflate(Z, Data) -> Decompressed
类型
相当于inflate(Z, Data, [])
inflate(Z, Data, Options) -> Decompressed
类型
解压缩尽可能多的数据。它可以引入一些输出延迟（读输入而不产生任何输出）。
目前唯一可用的选项是{exception_on_need_dict,boolean()}当需要预置字典进行解压缩时，控制函数是否应该抛出异常。当设置为false时，need_dictionary将返回一个元组。详情请参阅inflateSetDictionary/2。
警告
此选项默认true为向后兼容，但我们打算在未来版本中删除异常行为。需要手动处理字典的新代码应始终指定{exception_on_need_dict,false}。
inflateChunk(Z) -> Decompressed | {more, Decompressed}
类型
警告
此功能已弃用，将在未来版本中删除。safeInflate/2改为使用。
读取下一个未压缩的数据块，通过初始化inflateChunk/2。
这个函数在返回的时候会被重复调用{more, Decompressed}。
inflateChunk(Z, Data) -> Decompressed | {more, Decompressed}
类型
警告
此功能已弃用，将在未来版本中删除。safeInflate/2改为使用。
就像inflate/2，但解压缩的数据不会超过通过配置的缓冲区setBufSize/2。在压缩率高的流中进行解压缩时很有用，这样少量的压缩输入可以扩展到1000倍。
{more, Decompressed}当有更多的输出可用时，此函数返回并inflateChunk/1用于读取它。
该功能可以引入一些输出延迟（读输入而不产生任何输出）。
如果需要预设词典进行进一步解压缩，则会引发异常。详情请参阅inflateSetDictionary/2。
例子：
walk(Compressed, Handler) ->
Z = zlib:open(),
zlib:inflateInit(Z),
% Limit single uncompressed chunk size to 512kb
zlib:setBufSize(Z, 512 * 1024),
loop(Z, Handler, zlib:inflateChunk(Z, Compressed)),
zlib:inflateEnd(Z),
zlib:close(Z).
loop(Z, Handler, {more, Uncompressed}) ->
Handler(Uncompressed),
loop(Z, Handler, zlib:inflateChunk(Z)
loop(Z, Handler, Uncompressed) ->
Handler(Uncompressed).
inflateEnd(Z) -> ok
类型
结束充气会话并清理所有使用的数据。请注意，data_error如果没有找到流的末尾（意味着并非所有数据都未压缩），则此函数会引发异常。
inflateGetDictionary(Z) -> Dictionary
类型
返回流正在使用的解压字典。此功能必须在inflateInit/1,2和之间调用inflateEnd。
仅当使用zlib> = 1.2.8编译ERTS时才受支持。
inflateInit(Z) -> ok
类型
初始化zlib流以进行解压缩。
inflateInit(Z, WindowBits) -> ok
类型
初始化zlib流上的解压缩会话。
WindowBits是最大窗口大小（历史缓冲区的大小）的基础两倍对数。它应该在8到15的范围内。默认为15如果inflateInit/1使用。
如果将窗口大小较大的压缩流指定为输入，则会inflate/2引发data_error异常。
负值WindowBits会使zlib忽略流中的zlib头（和校验和）。请注意，zlib源只提到这是一个未记录的功能。
inflateReset(Z) -> ok
类型
等同于inflateEnd/1后面inflateInit/1，但不释放并重新分配所有内部解压缩状态。该流将保留可能由其设置的属性inflateInit/1,2。
inflateSetDictionary(Z, Dictionary) -> ok
类型
从指定的未压缩字节序列初始化解压字典。此函数必须作为对膨胀操作（例如，safeInflate/2）返回的响应来调用，{need_dictionary,Adler,Output}或者在弃用的函数中引发{'EXIT',{{need_dictionary,Adler},_StackTrace}}异常。
压缩器选择的字典可以通过调用膨胀函数返回或抛出的Adler值来确定。压缩器和解压缩器必须使用相同的字典（请参阅deflateSetDictionary/2）。
设置好字典后，应该重新进行充气操作，而不需要新的输入。
例子：
deprecated_unpack(Z, Compressed, Dict) ->
case catch zlib:inflate(Z, Compressed) of
{'EXIT',{{need_dictionary,_DictID},_}} ->
ok = zlib:inflateSetDictionary(Z, Dict),
Uncompressed = zlib:inflate(Z, []
Uncompressed ->
Uncompressed
end.
new_unpack(Z, Compressed, Dict) ->
case zlib:inflate(Z, Compressed, [{exception_on_need_dict, false}]) of
{need_dictionary, _DictId, Output} ->
ok = zlib:inflateSetDictionary(Z, Dict),
[Output | zlib:inflate(Z, [])];
Uncompressed ->
Uncompressed
end.
open() -> zstream()
打开一个zlib流。
safeInflate(Z, Data) -> Result
类型
一样inflate/2，但是一旦它扩展到一个很小的实现定义的阈值之外就会返回。解压缩可能被恶意制作的不受信任的输入，直到系统内存不足时才有用。
此函数返回{continue | finished, Output}，其中Output是在此调用中解压缩的数据。如果需要，可以在每次调用中对新输入进行排队，并且{finished, Output}一旦解压所有排队数据，该函数就会返回。
该功能可以引入一些输出延迟（读输入而不产生任何输出）。
如果需要预设字典进行进一步解压缩，则此函数将返回一个need_dictionary元组。请参阅inflateSetDictionary/2）了解详情。
例子：
walk(Compressed, Handler) ->
Z = zlib:open(),
zlib:inflateInit(Z),
loop(Z, Handler, zlib:safeInflate(Z, Compressed)),
zlib:inflateEnd(Z),
zlib:close(Z).
loop(Z, Handler, {continue, Output}) ->
Handler(Output),
loop(Z, Handler, zlib:safeInflate(Z, [])
loop(Z, Handler, {finished, Output}) ->
Handler(Output).
setBufSize(Z, Size) -> ok
类型
设置中间缓冲区大小。
警告
此功能已弃用，将在未来版本中删除。
uncompress(Data) -> Decompressed
类型
用zlib头和校验和解压缩数据。
unzip(Data) -> Decompressed
类型
不使用zlib头和校验和来解压缩数据。
zip(Data) -> Compressed
类型
压缩没有zlib头和校验和的数据。
