zlib
Zlib Compression interface.
The zlib module provides an API for the zlib library (http://www.zlib.org). It is used to compress and decompress data. The data format is described by RFCs 1950 to 1952.
A typical (compress) usage looks like:
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])
In all functions errors, {'EXIT',{Reason,Backtrace}}
,
might be thrown, where Reason
describes the
error. Typical reasons are:
badarg
-
Bad argument
data_error
-
The data contains errors
stream_error
-
Inconsistent stream state
einval
-
Bad value or wrong function called
{need_dictionary,Adler32}
-
See
inflate/2
DATA TYPES
iodata = iolist() | binary() iolist = [char() | binary() | iolist()] a binary is allowed as the tail of the list zstream = a zlib stream, see open/0
Functions
open() -> Z
Z = zstream()
Open a zlib stream.
close(Z) -> ok
Z = zstream()
Closes the stream referenced by Z
.
deflateInit(Z) -> ok
Z = zstream()
Same as zlib:deflateInit(Z, default)
.
deflateInit(Z, Level) -> ok
Z = zstream()
Level = none | default | best_speed | best_compression | 0..9
Initialize a zlib stream for compression.
Level
decides the compression level to be used, 0
(none
), gives no compression at all, 1
(best_speed
) gives best speed and 9
(best_compression
) gives best compression.
deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) -> ok
Z = zstream()
Level = none | default | best_speed | best_compression | 0..9
Method = deflated
WindowBits = 9..15|-9..-15
MemLevel = 1..9
Strategy = default|filtered|huffman_only
Initiates a zlib stream for compression.
The Level
parameter decides the compression level to be
used, 0 (none
), gives no compression at all, 1
(best_speed
) gives best speed and 9
(best_compression
) gives best compression.
The Method
parameter decides which compression method to use,
currently the only supported method is deflated
.
The WindowBits
parameter is the base two logarithm
of the window size (the size of the history buffer). It
should be in the range 9 through 15. Larger values
of this parameter result in better compression at the
expense of memory usage. The default value is 15 if
deflateInit/2
. A negative WindowBits
value suppresses the zlib header (and checksum) from the
stream. Note that the zlib source mentions this only as a
undocumented feature.
The MemLevel
parameter specifies how much memory
should be allocated for the internal compression
state. MemLevel
=1 uses minimum memory but is slow and
reduces compression ratio; MemLevel
=9 uses maximum
memory for optimal speed. The default value is 8.
The Strategy
parameter is used to tune the
compression algorithm. Use the value default
for
normal data, filtered
for data produced by a filter
(or predictor), or huffman_only
to force Huffman
encoding only (no string match). Filtered data consists
mostly of small values with a somewhat random
distribution. In this case, the compression algorithm is
tuned to compress them better. The effect of
filtered
is to force more Huffman coding and less
string matching; it is somewhat intermediate between
default
and huffman_only
. The Strategy
parameter only affects the compression ratio but not the
correctness of the compressed output even if it is not set
appropriately.
deflate(Z, Data) -> Compressed
Z = zstream()
Data = iodata()
Compressed = iolist()
Same as deflate(Z, Data, none)
.
deflate(Z, Data, Flush) ->
Z = zstream()
Data = iodata()
Flush = none | sync | full | finish
Compressed = iolist()
deflate/3
compresses as much data as possible, and
stops when the input buffer becomes empty. It may introduce
some output latency (reading input without producing any
output) except when forced to flush.
If the parameter Flush
is set to sync
, all
pending output is flushed to the output buffer and the
output is aligned on a byte boundary, so that the
decompressor can get all input data available so far.
Flushing may degrade compression for some compression algorithms and so
it should be used only when necessary.
If Flush
is set to full
, all output is flushed as with
sync
, and the compression state is reset so that decompression can
restart from this point if previous compressed data has been damaged or if
random access is desired. Using full
too often can seriously degrade
the compression.
If the parameter Flush
is set to finish
,
pending input is processed, pending output is flushed and
deflate/3
returns. Afterwards the only possible
operations on the stream are deflateReset/1
or deflateEnd/1
.
Flush
can be set to finish
immediately after
deflateInit
if all compression is to be done in one step.
zlib:deflateInit(Z), B1 = zlib:deflate(Z,Data), B2 = zlib:deflate(Z,<< >>,finish), zlib:deflateEnd(Z), list_to_binary([B1,B2])
deflateSetDictionary(Z, Dictionary) -> Adler32
Z = zstream()
Dictionary = binary()
Adler32 = integer()
Initializes the compression dictionary from the given byte
sequence without producing any compressed output. This
function must be called immediately after
deflateInit/[1|2|6]
or deflateReset/1
, before
any call of deflate/3
. The compressor and
decompressor must use exactly the same dictionary (see
inflateSetDictionary/2
). The adler checksum of the
dictionary is returned.
deflateReset(Z) -> ok
Z = zstream()
This function is equivalent to deflateEnd/1
followed by deflateInit/[1|2|6]
, but does not free
and reallocate all the internal compression state. The
stream will keep the same compression level and any other
attributes.
deflateParams(Z, Level, Strategy) -> ok
Z = zstream()
Level = none | default | best_speed | best_compression | 0..9
Strategy = default|filtered|huffman_only
Dynamically update the compression level and compression
strategy. The interpretation of Level
and
Strategy
is as in deflateInit/6
. This can be
used to switch between compression and straight copy of the
input data, or to switch to a different kind of input data
requiring a different strategy. If the compression level is
changed, the input available so far is compressed with the
old level (and may be flushed); the new level will take
effect only at the next call of deflate/3
.
Before the call of deflateParams, the stream state must be set as for
a call of deflate/3
, since the currently available input may have to
be compressed and flushed.
deflateEnd(Z) -> ok
Z = zstream()
End the deflate session and cleans all data used.
Note that this function will throw an data_error
exception if the last call to
deflate/3
was not called with Flush
set to
finish
.
inflateInit(Z) -> ok
Z = zstream()
Initialize a zlib stream for decompression.
inflateInit(Z, WindowBits) -> ok
Z = zstream()
WindowBits = 9..15|-9..-15
Initialize decompression session on zlib stream.
The WindowBits
parameter is the base two logarithm
of the maximum window size (the size of the history buffer).
It should be in the range 9 through 15.
The default value is 15 if inflateInit/1
is used.
If a compressed stream with a larger window size is
given as input, inflate() will throw the data_error
exception. A negative WindowBits
value makes zlib ignore the
zlib header (and checksum) from the stream. Note that the zlib
source mentions this only as a undocumented feature.
inflate(Z, Data) -> DeCompressed
Z = zstream()
Data = iodata()
DeCompressed = iolist()
inflate/2
decompresses as much data as possible.
It may some introduce some output latency (reading
input without producing any output).
If a preset dictionary is needed at this point (see
inflateSetDictionary
below), inflate/2
throws a
{need_dictionary,Adler}
exception where Adler
is
the adler32 checksum of the dictionary chosen by the
compressor.
inflateSetDictionary(Z, Dictionary) -> ok
Z = zstream()
Dictionary = binary()
Initializes the decompression dictionary from the given
uncompressed byte sequence. This function must be called
immediately after a call of inflate/2
if this call
threw a {need_dictionary,Adler}
exception.
The dictionary chosen by the
compressor can be determined from the Adler value thrown
by the call to inflate/2
. The compressor and decompressor
must use exactly the same dictionary (see deflateSetDictionary/2
).
Example:
unpack(Z, Compressed, Dict) -> case catch zlib:inflate(Z, Compressed) of \011 {'EXIT',{{need_dictionary,DictID},_}} -> \011 zlib:inflateSetDictionary(Z, Dict), \011 Uncompressed = zlib:inflate(Z, []); \011 Uncompressed -> \011 Uncompressed end.
inflateReset(Z) -> ok
Z = zstream()
This function is equivalent to inflateEnd/1
followed
by inflateInit/1
, but does not free and reallocate all
the internal decompression state. The stream will keep
attributes that may have been set by inflateInit/[1|2]
.
inflateEnd(Z) -> ok
Z = zstream()
End the inflate session and cleans all data used. Note
that this function will throw a data_error
exception
if no end of stream was found (meaning that not all data
has been uncompressed).
setBufSize(Z, Size) -> ok
Z = zstream()
Size = integer()
Sets the intermediate buffer size.
getBufSize(Z) -> Size
Z = zstream()
Size = integer()
Get the size of intermediate buffer.
crc32(Z) -> CRC
Z = zstream()
CRC = integer()
Get the current calculated CRC checksum.
crc32(Z, Binary) -> CRC
Z = zstream()
Binary = binary()
CRC = integer()
Calculate the CRC checksum for Binary
.
crc32(Z, PrevCRC, Binary) -> CRC
Z = zstream()
PrevCRC = integer()
Binary = binary()
CRC = integer()
Update a running CRC checksum for Binary
.
If Binary
is the empty binary, this function returns
the required initial value for the crc.
Crc = lists:foldl(fun(Bin,Crc0) -> \011 zlib:crc32(Z, Crc0, Bin), \011 end, zlib:crc32(Z,<< >>), Bins)
crc32_combine(Z, CRC1, CRC2, Size2) -> CRC
Z = zstream()
CRC = integer()
CRC1 = integer()
CRC2 = integer()
Size2 = integer()
Combine two CRC checksums into one. For two binaries,
Bin1
and Bin2
with sizes of Size1
and
Size2
, with CRC checksums CRC1
and
CRC2
. crc32_combine/4
returns the CRC
checksum of <<Bin1/binary,Bin2/binary>>
, requiring
only CRC1
, CRC2
, and Size2
.
adler32(Z, Binary) -> Checksum
Z = zstream()
Binary = binary()
Checksum = integer()
Calculate the Adler-32 checksum for Binary
.
adler32(Z, PrevAdler, Binary) -> Checksum
Z = zstream()
PrevAdler = integer()
Binary = binary()
Checksum = integer()
Update a running Adler-32 checksum for Binary
.
If Binary
is the empty binary, this function returns
the required initial value for the checksum.
Crc = lists:foldl(fun(Bin,Crc0) -> \011 zlib:adler32(Z, Crc0, Bin), \011 end, zlib:adler32(Z,<< >>), Bins)
adler32_combine(Z, Adler1, Adler2, Size2) -> Adler
Z = zstream()
Adler = integer()
Adler1 = integer()
Adler2 = integer()
Size2 = integer()
Combine two Adler-32 checksums into one. For two binaries,
Bin1
and Bin2
with sizes of Size1
and
Size2
, with Adler-32 checksums Adler1
and
Adler2
. adler32_combine/4
returns the Adler
checksum of <<Bin1/binary,Bin2/binary>>
, requiring
only Adler1
, Adler2
, and Size2
.
compress(Binary) -> Compressed
Binary = Compressed = binary()
Compress a binary (with zlib headers and checksum).
uncompress(Binary) -> Decompressed
Binary = Decompressed = binary()
Uncompress a binary (with zlib headers and checksum).
zip(Binary) -> Compressed
Binary = Compressed = binary()
Compress a binary (without zlib headers and checksum).
unzip(Binary) -> Decompressed
Binary = Decompressed = binary()
Uncompress a binary (without zlib headers and checksum).
gzip(Data) -> Compressed
Binary = Compressed = binary()
Compress a binary (with gz headers and checksum).
gunzip(Bin) -> Decompressed
Binary = Decompressed = binary()
Uncompress a binary (with gz headers and checksum).
- open/0
- close/1
- deflateInit/1
- deflateInit/2
- deflateInit/6
- deflate/2
- deflate/3
- deflateSetDictionary/2
- deflateReset/1
- deflateParams/3
- deflateEnd/1
- inflateInit/1
- inflateInit/2
- inflate/2
- inflateSetDictionary/2
- inflateReset/1
- inflateEnd/1
- setBufSize/2
- getBufSize/1
- crc32/1
- crc32/2
- crc32/3
- crc32_combine/4
- adler32/2
- adler32/3
- adler32_combine/4
- compress/1
- uncompress/1
- zip/1
- unzip/1
- gzip/1
- gunzip/1