From 57c3246511434f42214e113b8902af10ab9cca49 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Tue, 21 Jun 2016 15:50:34 +0200 Subject: erts: Editorial changes --- erts/doc/src/zlib.xml | 511 +++++++++++++++++++++++++++++--------------------- 1 file changed, 295 insertions(+), 216 deletions(-) (limited to 'erts/doc/src/zlib.xml') diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml index a3c94e4a7f..138414a880 100644 --- a/erts/doc/src/zlib.xml +++ b/erts/doc/src/zlib.xml @@ -30,13 +30,18 @@ zlib.xml zlib - Zlib Compression interface. + 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:

+

This module provides an API for the zlib library + (www.zlib.net). + It is used to compress and decompress data. + The data format is described by + RFC 1950, + RFC 1951, and + RFC 1952.

+ +

A typical (compress) usage is as follows:

+ 
 Z = zlib:open(),
 ok = zlib:deflateInit(Z,default),
@@ -50,29 +55,25 @@ 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:

+ can be thrown, where Reason describes the error.

+ +

Typical Reasonss:

+ badarg - -

Bad argument

+ Bad argument. data_error - -

The data contains errors

+ The data contains errors. stream_error - -

Inconsistent stream state

- + Inconsistent stream state. einval - -

Bad value or wrong function called

- + Bad value or wrong function called. {need_dictionary,Adler32} - -

See inflate/2

+ See inflate/2. @@ -81,7 +82,7 @@ list_to_binary([Compressed|Last]) -

A zlib stream, see open/0. +

A zlib stream, see open/0.

@@ -104,129 +105,144 @@ list_to_binary([Compressed|Last]) + - Calculate the adler checksum + Calculate the Adler checksum. -

Calculate the Adler-32 checksum for Data.

+

Calculates the Adler-32 checksum for Data.

 + - Calculate the adler checksum + Calculate the Adler checksum. -

Update a running Adler-32 checksum for Data. - If Data is the empty binary or the empty iolist, this function returns - the required initial value for the checksum.

+

Updates a running Adler-32 checksum for Data. + If Data is the empty binary or the empty iolist, + this function returns the required initial value for the checksum.

+

Example:

 Crc = lists:foldl(fun(Data,Crc0) ->
                       zlib:adler32(Z, Crc0, Data),
                   end, zlib:adler32(Z,<< >>), Datas)
 + - Combine two Adler-32 checksums + Combine two Adler-32 checksums. -

Combine two Adler-32 checksums into one. For two binaries or iolists, - Data1 and Data2 with sizes of Size1 and - Size2, with Adler-32 checksums Adler1 and - Adler2. adler32_combine/4 returns the Adler - checksum of [Data1,Data2], requiring - only Adler1, Adler2, and Size2. -

+

Combines two Adler-32 checksums into one. For two binaries or + iolists, Data1 and Data2 with sizes of Size1 + and Size2, with Adler-32 checksums + Adler1 and Adler2.

+

This function returns the Adler checksum of + [Data1,Data2], requiring only Adler1, + Adler2, and Size2.

 + - Close a stream + Close a stream.

Closes the stream referenced by Z.

 + - Compress data with standard zlib functionality + Compress data with standard zlib functionality. -

Compress data (with zlib headers and checksum).

+

Compresses data with zlib headers and checksum.

 + - Get current CRC + Get current CRC. -

Get the current calculated CRC checksum.

+

Gets the current calculated CRC checksum.

 + - Calculate CRC + Calculate CRC. -

Calculate the CRC checksum for Data.

+

Calculates the CRC checksum for Data.

 + - Calculate CRC + Calculate CRC. -

Update a running CRC checksum for Data. - If Data is the empty binary or the empty iolist, this function returns - the required initial value for the crc.

+

Updates a running CRC checksum for Data. + If Data is the empty binary or the empty iolist, + this function returns the required initial value for the CRC.

+

Example:

 Crc = lists:foldl(fun(Data,Crc0) ->
                       zlib:crc32(Z, Crc0, Data),
                   end, zlib:crc32(Z,<< >>), Datas)
 + - Combine two CRC's + Combine two CRCs. -

Combine two CRC checksums into one. For two binaries or iolists, - Data1 and Data2 with sizes of Size1 and - Size2, with CRC checksums CRC1 and - CRC2. crc32_combine/4 returns the CRC - checksum of [Data1,Data2], requiring - only CRC1, CRC2, and Size2. -

+

Combines two CRC checksums into one. For two binaries or iolists, + Data1 and Data2 with sizes of Size1 and + Size2, with CRC checksums CRC1 + and CRC2.

+

This function returns the CRC checksum of + [Data1,Data2], requiring only CRC1, + CRC2, and Size2.

 - Compress data + Compress data.

Same as deflate(Z, Data, none).

 + - Compress data + Compress data. -

deflate/3 compresses as much data as possible, and - stops when the input buffer becomes empty. It may introduce +

Compresses as much data as possible, and + stops when the input buffer becomes empty. It can introduce some output latency (reading input without producing any output) except when forced to flush.

-

If the parameter Flush is set to sync, all +

If 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.

+ Flushing can degrade compression for some compression algorithms; + thus, use it 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 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.

+

Example:

- 
 zlib:deflateInit(Z),
 B1 = zlib:deflate(Z,Data),
 B2 = zlib:deflate(Z,<< >>,finish),
@@ -237,184 +253,231 @@ list_to_binary([B1,B2])
- End deflate session + End deflate session. -

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.

+

Ends the deflate session and cleans all data used. Notice that this + function throws a data_error exception if the last call to + deflate/3 + was not called with Flush set to finish.

 - Initialize a session for compression + Initialize a session for compression.

Same as zlib:deflateInit(Z, default).

 + - Initialize a session for compression + Initialize a session for compression. -

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.

+

Initializes a zlib stream for compression.

+

Level decides the compression level to be + used:

+ + 0 (none), gives no compression + 1 (best_speed) gives best speed + 9 (best_compression) gives best compression + + - Initialize a session for compression + Initialize a session for compression.

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 8 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), huffman_only to force Huffman encoding - only (no string match), or rle to limit match - distances to one (run-length encoding). 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 filteredis to - force more Huffman coding and less string matching; it is - somewhat intermediate between default and - huffman_only. rle is designed to be almost as - fast as huffman_only, but give better compression for PNG - image data. The Strategy parameter only - affects the compression ratio but not the correctness of the - compressed output even if it is not set appropriately.

+ + Level + +

Compression level to use:

+ + 0 (none), gives no compression + 1 (best_speed) gives best speed + 9 (best_compression) gives best compression + + + Method + +

Compression method to use, currently the only supported method + is deflated.

+ + WindowBits + +

The base two logarithm of the window size (the size of the + history buffer). It is to be in the range 8 through 15. Larger + values result in better compression at the expense of memory + usage. Defaults to 15 if + deflateInit/2 is used. A negative + WindowBits value suppresses the zlib header + (and checksum) from the stream. Notice that the zlib source + mentions this only as a undocumented feature.

+ + MemLevel + +

Specifies how much memory is to 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. Defaults to 8.

+ + Strategy + +

Tunes the compression algorithm. Use the following values:

+ + default for normal data + filtered for data produced by a filter (or + predictor) + huffman_only to force Huffman encoding only + (no string match) + rle to limit match distances to one (run-length + encoding) + +

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. + rle is designed to be almost as fast as + huffman_only, but gives better compression for PNG image + data.

+

Strategy affects only the compression ratio, + but not the correctness of the compressed output even if it is not + set appropriately.

+ + + - Dynamicly update deflate parameters + Dynamicly update deflate parameters. -

Dynamically update the compression level and compression - strategy. The interpretation of Level and - Strategy is as in deflateInit/6. This can be +

Dynamically updates 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.

+ old level (and can be flushed); the new level takes + 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, as the currently available + input may have to be compressed and flushed.

 + - Reset the deflate session - -

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 + Reset the deflate session. + +

Equivalent to + deflateEnd/1 + followed by + deflateInit/1,2,6, + but does not free and reallocate all the internal compression state. + The stream keeps the same compression level and any other attributes.

 + - Initialize the compression dictionary + Initialize the compression dictionary. -

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.

+

Initializes the compression dictionary from the specified 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 the same dictionary (see + + inflateSetDictionary/2).

+

The Adler checksum of the dictionary is returned.

 + - Get buffer size + Get buffer size. -

Get the size of intermediate buffer.

+

Gets the size of the intermediate buffer.

 + - Uncompress data with gz header + Uncompress data with gz header. -

Uncompress data (with gz headers and checksum).

+

Uncompresses data with gz headers and checksum.

 + - Compress data with gz header + Compress data with gz header. -

Compress data (with gz headers and checksum).

+

Compresses data with gz headers and checksum.

 + - Decompress data + Decompress data. -

inflate/2 decompresses as much data as possible. - It may introduce some output latency (reading +

Decompresses as much data as possible. + It can 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/2), inflate/2 throws a + {need_dictionary,Adler} exception, where Adler is + the Adler-32 checksum of the dictionary chosen by the compressor.

 + - Read next uncompressed chunk + Read next uncompressed chunk. -

Read next chunk of uncompressed data, initialized by - inflateChunk/2.

-

This function should be repeatedly called, while it returns +

Reads the next chunk of uncompressed data, initialized by + inflateChunk/2.

+

This function is to be repeatedly called, while it returns {more, Decompressed}.

 + - Decompress data with limited output size + Decompress data with limited output size. -

Like inflate/2, but decompress no more data than - will fit in the buffer configured via setBufSize/2. +

Like inflate/2, + but decompresses no more data than will fit in the buffer configured + through setBufSize/2. Is is useful when decompressing a stream with a high compression - ratio such that a small amount of compressed input may expand up to - 1000 times. - It returns {more, Decompressed}, when there is more output - available, and inflateChunk/1 should be used to read it. - It may introduce some output latency (reading + ratio, such that a small amount of compressed input can expand up to + 1000 times.

+

This function returns {more, Decompressed}, when there is + more output available, and + inflateChunk/1 + is to be used to read it.

+

This function can introduce some output latency (reading input without producing any output).

If a preset dictionary is needed at this point (see - inflateSetDictionary below), inflateChunk/2 throws a - {need_dictionary,Adler} exception where Adler is - the adler32 checksum of the dictionary chosen by the - compressor.

- + + inflateSetDictionary/2), this function throws a + {need_dictionary,Adler} exception, where Adler is + the Adler-32 checksum of the dictionary chosen by the compressor.

+

Example:

 walk(Compressed, Handler) ->
     Z = zlib:open(),
@@ -429,65 +492,76 @@ loop(Z, Handler, {more, Uncompressed}) ->
     Handler(Uncompressed),
     loop(Z, Handler, zlib:inflateChunk(Z));
 loop(Z, Handler, Uncompressed) ->
-    Handler(Uncompressed).
-
+ Handler(Uncompressed). + - End inflate session + End inflate session. -

End the inflate session and cleans all data used. Note - that this function will throw a data_error exception +

Ends the inflate session and cleans all data used. Notice + that this function throws a data_error exception if no end of stream was found (meaning that not all data has been uncompressed).

 + - Initialize a session for decompression + Initialize a session for decompression. -

Initialize a zlib stream for decompression.

+

Initializes a zlib stream for decompression.

 + - Initialize a session for decompression + Initialize a session for decompression. -

Initialize decompression session on zlib stream.

-

The WindowBits parameter is the base two logarithm +

Initializes a decompression session on zlib stream.

+

WindowBits is the base two logarithm of the maximum window size (the size of the history buffer). - It should be in the range 8 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.

+ It is to be in the range 8 through 15. Default to 15 if + inflateInit/1 + is used.

+

If a compressed stream with a larger window size is specified as + input, inflate/2 + throws the data_error exception.

+

A negative WindowBits value makes zlib + ignore the zlib header (and checksum) from the stream. Notice that + the zlib source mentions this only as a undocumented feature.

 + - >Reset the inflate session + >Reset the inflate session. -

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].

+

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 could have been set by + inflateInit/1,2.

 + - Initialize the decompression dictionary + Initialize the decompression dictionary. -

Initializes the decompression dictionary from the given +

Initializes the decompression dictionary from the specified 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).

+ 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 the same dictionary (see + + deflateSetDictionary/2).

Example:

 unpack(Z, Compressed, Dict) ->
@@ -500,39 +574,44 @@ unpack(Z, Compressed, Dict) ->
      end.
 + - Open a stream and return a stream reference + Open a stream and return a stream reference. -

Open a zlib stream.

+

Opens a zlib stream.

 + - Set buffer size + Set buffer size.

Sets the intermediate buffer size.

 + - Uncompress data with standard zlib functionality + Uncompress data with standard zlib functionality. -

Uncompress data (with zlib headers and checksum).

+

Uncompresses data with zlib headers and checksum.

 + - Uncompress data without the zlib headers + Uncompress data without the zlib headers. -

Uncompress data (without zlib headers and checksum).

+

Uncompresses data without zlib headers and checksum.

 + - Compress data without the zlib headers + Compress data without the zlib headers. -

Compress data (without zlib headers and checksum).

+

Compresses data without zlib headers and checksum.

 -- cgit v1.2.3