gzip Jens Axel Søgaard

----------------------------------------------------------------------
  _gzip_                                          Jens Axel Søgaard
----------------------------------------------------------------------

----------------------------------------------------------------------
HISTORY
----------------------------------------------------------------------
2009-feb-6   Port to 4xx.
             Added support for mac os x.

2007-feb-17  First release. 
               - open-input-gz-file
               - open-output-gz-file
               - read-gz-file
               - compress-bytes
               - uncompress-bytes

----------------------------------------------------------------------
INTRODUCTION
----------------------------------------------------------------------

This library provides bindings to the general purpose compression
library zlib written by Jean-loup Gailly and Mark Adler.

    <http://www.zlib.net/manual.html>

For convenience for Windows users, the dll-file zlib1.dll is included 
with this PLaneT package.

Note, that gzip-files are already supported in (lib "inflate.ss")
and (lib "deflate.ss"), so this is just an alternative.

----------------------------------------------------------------------
INSTALLATION
----------------------------------------------------------------------

(require (planet soegaard/gzip:2:0/gzip))

On Mac and Unix download zlib, if you get an error message
from the above.
    
----------------------------------------------------------------------
FILE OPERATIONS
----------------------------------------------------------------------

> open-input-gz-file : path -> input-port

The function open-input-gz-file opens an existing gz-file and
returns an input port. 

Example:

   > (define in (open-input-gz-file (string->path "fooo.gz")))
   > (read-bytes 9 in)
   #"123344445"
   > (close-input-port in)


> open-output-gz-file : path ['replace]-> output-port

The function open-output-gz-file opens a file and returns
an output port. Output written to the output port is compressed
using the gzip algorithm. Remember to close the port, before
reading from the file.

If the file exists the exception exn:file-system:exists will be raised,
unless the option 'replace is present, in that case the existing
file will be replaced.

Example:

  (define out (open-output-gz-file "fooo.gz" 'replace))
  (write-bytes #"123" out)
  (write-bytes #"344445" out)
  (close-output-port out)

> read-gz-file : path -> bytes

Uncompresses the entire file given by path, and returns a 
byte string as the result.

Faster than using open-input-gz-file and reading everything
into a byte string.

----------------------------------------------------------------------
IN MEMORY COMPRESSION
----------------------------------------------------------------------

> compress-bytes : bytes -> bytes

Compresses the bytes in the input and returns a byte string
containing the compressed result.

Example:

  > (compress-bytes #"1234")
  #"x\2343426\1\0\1\370\0\313"

> uncompress-bytes : bytes integer -> bytes

A call (uncompress-bytes compressed-bytes uncompressed-size) will
uncompress the bytes in compressed-bytes and return the uncompressed
result as a byte string. The size of the uncompressed data must
be given as the second argument.

Example:
  > (uncompress-bytes
      (compress-bytes #"1234")
      4)
  #"1234"

----------------------------------------------------------------------
KEYWORDS
----------------------------------------------------------------------

Keywords: _compression_ _decompression_ _gzip_ _gz_ _zlib_