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头和校验和的数据。