Description

A gzip (RFC1951 + RFC1952) compression and decompression library

Author

Oskar Schirmer and felix winkelmann

Version

Usage

(require-extension z3)

Download

z3.egg

Documentation

Provides functions to read and write compressed data using the gzip algorithm. This extension includes code from Oskar Schirmers excellent z3liblibrary.

Errors occurring in inflation/deflation procedures will result in a composite condition of the kinds exn and z3.

Raw data interface

procedure: (z3:encode-init #!key buffer buffer-size tellwhen thrmin thrmax initialgrant preferlonger)

Initializes compression of data into a memory buffer. Various keyword arguments can be supplied to control compression:

buffer
The target buffer for the compressed data
buffer-size
maximal size of the compressed data
tellwhen
Frequency for code size estimation (0 for none, i.e. full block usage)
thrmin, thrmax
Threshold for block close decision
initialgrant
For threshold comparison, all but the first slice are asumed to be incremented by this value to roughly compensate RFC1951 block dynamic table size
preferlonger
When non-zero, the compressor will try to find a longer match at n+1 and prefer it over a previous match at n

Returns a z3 handle.

procedure: (z3:encode Z3HANDLE RECEIVER DATA [LENGTH])

Encode data (a string) into a memory buffer and returns the number of bytes written. If less data has been commpressed than given in the call, invoke z3:encode repeatedly with the remaining data. Returns #f when finished. Each time some compressed data is available, the one-argument procedure RECEIVER is called with a string containing a chunk of compressed data.

procedure: (z3:decode-init)

Initialize an in-memory decompression and return a z3 handle for it.

procedure: (z3:decode Z3HANDLE RECEIVER BUFFER [LENGTH])

Decode the compressed data in BUFFER (a string) and return the number of bytes decompressed.

procedure: (z3:handle? X)

Returns #t if X is a z3 handle or #f otherwise.

Buffer interface

procedure: (z3:encode-buffer STRING [START [END [DESTINATION]]])

Encodes the data in STRING with optional start- and end-positions. If DESTINATION is given, then the compressed data will be stored in that argument (which should be a string of sufficient size) and z3:encode-buffer returns the length of the compressed data. If no destination is given then a freshly allocated string is returned that contains the compressed data.

procedure: (z3:decode-buffer STRING [START [END]])

Decodes the compressed data in STRING and returns the uncompressed data. Optional start- and end-position may be given.

File-system interface

procedure: (z3:encode-file FILENO #!key level filename comment ostype extra)

Open a compressed file (specified by the file-descriptor in FILENO) for encoded data. The keyword arguments have the following meaning:

level
Desired compression-level in the range 1 .. 9, or 0 for selecting the default compression level
filename
The name of the file to compress, will be included in the gzip-file header
comment
An arbitrary comment
ostype
Operating system indicator byte (defaults to -1)
extra
Extra data to be encoded in the header

Returns a z3 file-handle.

procedure: (z3:write-encoded Z3FHANDLE DATA [LENGTH])

Writes DATA (a string) into a compressed file, optionally limited in length. Before a file has been encoded completely, this procedure must be called once more with DATA being #f to indicate that the compression process is finished.

procedure: (z3:decode-file FILENO)

Returns a z3 file-handle for reading the file designated by the file-descriptor FILENO.

procedure: (z3:read-decoded Z3FHANDLE [LENGTH])

Reads a chunk of decoded data from a compressed file. The length of the chunk can be given as an optional argument and defaults to 4096 bytes. Returns a string or the end-of-file object.

procedure: (z3:file-handle? X)

Returns #t if X is a z3 file handle or #f otherwise.

procedure: (z3:file-handle-fileno Z3FHANDLE)

Returns the file-descriptor associated with a z3 file-handle.

Port interface

procedure: (z3:open-compressed-input-file FILENAME)

Opens a compressed input file and returns a port that automatically decompresses the data as it is read.

procedure: (z3:open-compressed-output-file FILENAME #!key level comment ostype extra)

Creates a compressed file and returns an output-port. The keyword arguments have the same meaning as for the z3:encode-file procedure.

License

Copyright (c) 2005-2007 Oskar Schirmer.  All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the Software),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.