Doc/lib/libzlib.tex

   1 % XXX The module has been extended (by Jeremy and Andrew) but this
   2 % documentation is incorrect in some cases.
   3
   4 \section{\module{zlib} ---
   5          Compression compatible with \program{gzip}}
   6
   7 \declaremodule{builtin}{zlib}
   8 \modulesynopsis{Low-level interface to compression and decompression
   9                 routines compatible with \program{gzip}.}
  10
  11
  12 For applications that require data compression, the functions in this
  13 module allow compression and decompression, using the zlib library.
  14 The zlib library has its own home page at
  15 \url{http://www.cdrom.com/pub/infozip/zlib/}.  Version 1.1.3 is the
  16 most recent version as of April 1999; use a later version if one
  17 is available.  There are known incompatibilities between the Python
  18 module and earlier versions of the zlib library.
  19
  20 The documentation for this module is woefully out of date.  In some
  21 cases, the doc strings have been updated more recently.  In other
  22 cases, they are both stale.
  23
  24 The available exception and functions in this module are:
  25
  26 \begin{excdesc}{error}
  27   Exception raised on compression and decompression errors.
  28 \end{excdesc}
  29
  30
  31 \begin{funcdesc}{adler32}{string\optional{, value}}
  32    Computes a Adler-32 checksum of \var{string}.  (An Adler-32
  33    checksum is almost as reliable as a CRC32 but can be computed much
  34    more quickly.)  If \var{value} is present, it is used as the
  35    starting value of the checksum; otherwise, a fixed default value is
  36    used.  This allows computing a running checksum over the
  37    concatenation of several input strings.  The algorithm is not
  38    cryptographically strong, and should not be used for
  39    authentication or digital signatures.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{compress}{string\optional{, level}}
  43   Compresses the data in \var{string}, returning a string contained
  44   compressed data.  \var{level} is an integer from \code{1} to
  45   \code{9} controlling the level of compression; \code{1} is fastest
  46   and produces the least compression, \code{9} is slowest and produces
  47   the most.  The default value is \code{6}.  Raises the
  48   \exception{error} exception if any error occurs.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{compressobj}{\optional{level}}
  52   Returns a compression object, to be used for compressing data streams
  53   that won't fit into memory at once.  \var{level} is an integer from
  54   \code{1} to \code{9} controlling the level of compression; \code{1} is
  55   fastest and produces the least compression, \code{9} is slowest and
  56   produces the most.  The default value is \code{6}.
  57 \end{funcdesc}
  58
  59 \begin{funcdesc}{crc32}{string\optional{, value}}
  60   Computes a CRC (Cyclic Redundancy Check)%
  61   \index{Cyclic Redundancy Check}
  62   \index{checksum!Cyclic Redundancy Check}
  63   checksum of \var{string}. If
  64   \var{value} is present, it is used as the starting value of the
  65   checksum; otherwise, a fixed default value is used.  This allows
  66   computing a running checksum over the concatenation of several
  67   input strings.  The algorithm is not cryptographically strong, and
  68   should not be used for authentication or digital signatures.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{decompress}{string\optional{, wbits\optional{, buffsize}}}
  72   Decompresses the data in \var{string}, returning a string containing
  73   the uncompressed data.  The \var{wbits} parameter controls the size of
  74   the window buffer.  If \var{buffsize} is given, it is used as the
  75   initial size of the output buffer.  Raises the \exception{error}
  76   exception if any error occurs.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{decompressobj}{\optional{wbits}}
  80   Returns a compression object, to be used for decompressing data
  81   streams that won't fit into memory at once.  The \var{wbits}
  82   parameter controls the size of the window buffer.
  83 \end{funcdesc}
  84
  85 Compression objects support the following methods:
  86
  87 \begin{methoddesc}[Compress]{compress}{string}
  88 Compress \var{string}, returning a string containing compressed data
  89 for at least part of the data in \var{string}.  This data should be
  90 concatenated to the output produced by any preceding calls to the
  91 \method{compress()} method.  Some input may be kept in internal buffers
  92 for later processing.
  93 \end{methoddesc}
  94
  95 \begin{methoddesc}[Compress]{flush}{\optional{mode}}
  96 All pending input is processed, and a string containing the remaining
  97 compressed output is returned.  \var{mode} can be selected from the
  98 constants \constant{Z_SYNC_FLUSH},  \constant{Z_FULL_FLUSH},  or
  99 \constant{Z_FINISH}, defaulting to \constant{Z_FINISH}.  \constant{Z_SYNC_FLUSH} and
 100 \constant{Z_FULL_FLUSH} allow compressing further strings of data and
 101 are used to allow partial error recovery on decompression, while
 102 \constant{Z_FINISH} finishes the compressed stream and
 103 prevents compressing any more data.  After calling
 104 \method{flush()} with \var{mode} set to \constant{Z_FINISH}, the
 105 \method{compress()} method cannot be called again; the only realistic
 106 action is to delete the object.
 107 \end{methoddesc}
 108
 109 Decompression objects support the following methods:
 110
 111 \begin{methoddesc}[Decompress]{decompress}{string}
 112 Decompress \var{string}, returning a string containing the
 113 uncompressed data corresponding to at least part of the data in
 114 \var{string}.  This data should be concatenated to the output produced
 115 by any preceding calls to the
 116 \method{decompress()} method.  Some of the input data may be preserved
 117 in internal buffers for later processing.
 118 \end{methoddesc}
 119
 120 \begin{methoddesc}[Decompress]{flush}{}
 121 All pending input is processed, and a string containing the remaining
 122 uncompressed output is returned.  After calling \method{flush()}, the
 123 \method{decompress()} method cannot be called again; the only realistic
 124 action is to delete the object.
 125 \end{methoddesc}
 126
 127 \begin{seealso}
 128   \seemodule{gzip}{reading and writing \program{gzip}-format files}
 129   \seetext{The zlib library home page is located at
 130            \url{http://www.cdrom.com/pub/infozip/zlib/}.}
 131 \end{seealso}