| % XXX The module has been extended (by Jeremy) but this documentation |
| % hasn't been updated completely. |
| |
| \section{\module{zlib} --- |
| Compression and decompression compatible with \program{gzip}.} |
| \declaremodule{builtin}{zlib} |
| |
| \modulesynopsis{Low-level interface to compression and decompression |
| routines compatible with \program{gzip}.} |
| |
| |
| For applications that require data compression, the functions in this |
| module allow compression and decompression, using the zlib library. |
| The zlib library has its own home page at |
| \url{http://www.cdrom.com/pub/infozip/zlib/}. Version 1.0.4 is the |
| most recent version as of December, 1997; use a later version if one |
| is available. |
| |
| The available exception and functions in this module are: |
| |
| \begin{excdesc}{error} |
| Exception raised on compression and decompression errors. |
| \end{excdesc} |
| |
| |
| \begin{funcdesc}{adler32}{string\optional{, value}} |
| Computes a Adler-32 checksum of \var{string}. (An Adler-32 |
| checksum is almost as reliable as a CRC32 but can be computed much |
| more quickly.) If \var{value} is present, it is used as the |
| starting value of the checksum; otherwise, a fixed default value is |
| used. This allows computing a running checksum over the |
| concatenation of several input strings. The algorithm is not |
| cryptographically strong, and should not be used for |
| authentication or digital signatures. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{compress}{string\optional{, level}} |
| Compresses the data in \var{string}, returning a string contained |
| compressed data. \var{level} is an integer from \code{1} to |
| \code{9} controlling the level of compression; \code{1} is fastest |
| and produces the least compression, \code{9} is slowest and produces |
| the most. The default value is \code{6}. Raises the |
| \exception{error} exception if any error occurs. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{compressobj}{\optional{level}} |
| Returns a compression object, to be used for compressing data streams |
| that won't fit into memory at once. \var{level} is an integer from |
| \code{1} to \code{9} controlling the level of compression; \code{1} is |
| fastest and produces the least compression, \code{9} is slowest and |
| produces the most. The default value is \code{6}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{crc32}{string\optional{, value}} |
| Computes a CRC (Cyclic Redundancy Check)% |
| \index{Cyclic Redundancy Check} |
| \index{checksum!Cyclic Redundancy Check} |
| checksum of \var{string}. If |
| \var{value} is present, it is used as the starting value of the |
| checksum; otherwise, a fixed default value is used. This allows |
| computing a running checksum over the concatenation of several |
| input strings. The algorithm is not cryptographically strong, and |
| should not be used for authentication or digital signatures. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{decompress}{string\optional{, wbits\optional{, buffsize}}} |
| Decompresses the data in \var{string}, returning a string containing |
| the uncompressed data. The \var{wbits} parameter controls the size of |
| the window buffer. If \var{buffsize} is given, it is used as the |
| initial size of the output buffer. Raises the \exception{error} |
| exception if any error occurs. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{decompressobj}{\optional{wbits}} |
| Returns a compression object, to be used for decompressing data |
| streams that won't fit into memory at once. The \var{wbits} |
| parameter controls the size of the window buffer. |
| \end{funcdesc} |
| |
| Compression objects support the following methods: |
| |
| \begin{methoddesc}[Compress]{compress}{string} |
| Compress \var{string}, returning a string containing compressed data |
| for at least part of the data in \var{string}. This data should be |
| concatenated to the output produced by any preceding calls to the |
| \method{compress()} method. Some input may be kept in internal buffers |
| for later processing. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Compress]{flush}{\optional{mode}} |
| All pending input is processed, and a string containing the remaining |
| compressed output is returned. \var{mode} can be selected from the |
| constants \constant{Z_SYNC_FLUSH}, \constant{Z_FULL_FLUSH}, or |
| \constant{Z_FINISH}, defaulting to \constant{Z_FINISH}. \constant{Z_SYNC_FLUSH} and |
| \constant{Z_FULL_FLUSH} allow compressing further strings of data and |
| are used to allow partial error recovery on decompression, while |
| \constant{Z_FINISH} finishes the compressed stream and |
| prevents compressing any more data. After calling |
| \method{flush()} with \var{mode} set to \constant{Z_FINISH}, the |
| \method{compress()} method cannot be called again; the only realistic |
| action is to delete the object. |
| \end{methoddesc} |
| |
| Decompression objects support the following methods: |
| |
| \begin{methoddesc}[Decompress]{decompress}{string} |
| Decompress \var{string}, returning a string containing the |
| uncompressed data corresponding to at least part of the data in |
| \var{string}. This data should be concatenated to the output produced |
| by any preceding calls to the |
| \method{decompress()} method. Some of the input data may be preserved |
| in internal buffers for later processing. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Decompress]{flush}{} |
| All pending input is processed, and a string containing the remaining |
| uncompressed output is returned. After calling \method{flush()}, the |
| \method{decompress()} method cannot be called again; the only realistic |
| action is to delete the object. |
| \end{methoddesc} |
| |
| \begin{seealso} |
| \seemodule{gzip}{reading and writing \program{gzip}-format files} |
| \end{seealso} |
| |
| |