'\"
'\" Copyright (c) 2008 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: zlib.n,v 1.2 2008/12/12 16:34:45 dkf Exp $
'\" 
.so man.macros
.TH zlib n 8.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
zlib \- compression and decompression operations
.SH SYNOPSIS
.nf
\fBzlib \fIsubcommand arg ...\fR
.fi
.BE
.SH DESCRIPTION
.PP
The \fBzlib\fR command provides access to the compression facilities of the
Zlib library. It has the following subcommands
.TP
\fBzlib adler32\fI string\fR ?\fIinitValue\fR?
.
Compute a checksum of binary string \fIstring\fR using the Adler-32 algorithm.
If given, \fIinitValue\fR is used to initialize the checksum engine.
.TP
\fBzlib compress\fI string\fR ?\fIlevel\fR?
.
.TP
\fBzlib crc32\fI string\fR ?\fIinitValue\fR?
.
Compute a checksum of binary string \fIstring\fR using the CRC-32 algorithm.
If given, \fIinitValue\fR is used to initialize the checksum engine.
.TP
\fBzlib decompress\fI string\fR ?\fIbufferSize\fR?
.
.TP
\fBzlib deflate\fI string\fR ?\fIlevel\fR?
.
.TP
\fBzlib gunzip\fI string\fR ?\fB\-headerVar \fIvarName\fR?
.
Return the uncompressed contents of binary string \fIstring\fR, which must
have been in gzip format. If \fB\-headerVar\fR is given, store a dictionary
describing the contents of the gzip header in the variable called
\fIvarName\fR.
'\" TODO: describe dict fields
.TP
\fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR? 
.
Return the compressed contents of binary string \fIstring\fR in gzip format.
If \fB\-level\fR is given, \fIlevel\fR gives the compression level to use
(from 0, which is uncompressed, to 9, maximally compressed). If \fB\-header\fR
is given, \fIdict\fR is a dictionary containing values used for the gzip
header.
'\" TODO: describe dict fields
.TP
\fBzlib inflate\fI string\fR ?\fIbufferSize\fR?
.
.TP
\fBzlib stack\fI channel\fR
.
.TP
\fBzlib stream\fI mode\fR ?\fIlevel\fR?
.
Creates a streaming compression or decompression command based on the
\fImode\fR, and return the name of the command. For a description of how that
command works, see \fBSTREAMING COMMAND\fR below. The following modes are
supported:
.RS
.TP
\fBzlib stream compress\fR
.
.TP
\fBzlib stream decompress\fR
.
.TP
\fBzlib stream deflate\fR
.
.TP
\fBzlib stream gunzip\fR
.
.TP
\fBzlib stream gzip\fR
.
.TP
\fBzlib stream inflate\fR
.
.RE
.TP
\fBzlib unstack\fI channel\fR
.
Reverses the effects of \fBzlib stack\fR on the channel called \fIchannel\fR.
.SH EXAMPLES
.PP
To compress a Tcl string, it should be first converted to a particular charset
encoding since the \fBzlib\fR command always operates on binary strings.
.PP
.CS
set compressed [\fBzlib deflate\fR [encoding convertto utf8 $string]]
.CE
.PP
When converting back, it is also important to reverse the charset encoding:
.PP
.CS
set string [encoding convertfrom utf8 [\fBzlib inflate\fR $compressed]]
.CE
.SH "SEE ALSO"
binary(n), chan(n), encoding(n)
.SH "KEYWORDS"
compress, decompress, deflate, gzip, inflate
'\" Local Variables:
'\" mode: nroff
'\" End: