% XXX The module has been extended (by Jeremy) but this documentation
% hasn't been updated completely.

\section{\module{zlib} ---
         Compression library 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}