ZLib

is a high-level wrapper around zlib.

Installation

(load "git@git.veitheller.de:carpentry/zlib.git@0.1.0")

Usage

The ZLib module provides two pairs of functions: deflate and inflate for strings, and deflate-bytes and inflate-bytes for binary data. Each pair works in tandem to provide you with data compression.

; deflate returns a Result of either binary data or an error message
(let [deflated (ZLib.deflate "mystring")]
  (match deflated
    ; inflate returns a Result of either a string or an error message
    (Success bin) (println* &(inflate bin))
    (Error msg) (IO.errorln &msg)))

Because it’s a Result type, we can apply combinators to it.

(=> (ZLib.deflate "mystring")
    (Result.and-then &ZLib.inflate)
    (Result.map-error &(fn [msg] (do (println* &msg) msg)))
)

You can also choose different levels of compression using deflate-with. The levels are defined in ZLib.ZLevel, and are NoCompression, BestSpeed, BestCompression, and DefaultCompression, which is, well, the default.

Binary data

deflate and inflate are bounded by String semantics: their input stops at the first NUL byte, and the compressed payload they pass around is opaque. Compressed data is full of NUL bytes, so if you want to write it to a file or send it over a socket—or if what you are compressing isn’t text in the first place—use the (Array Byte) API instead.

(=> (ZLib.deflate-bytes &(String.to-bytes "mystring"))
    (Result.and-then &ZLib.inflate-bytes))

It offers the same three entry points, deflate-bytes, deflate-bytes-with, and inflate-bytes, all of which take and return (Array Byte).

ZLevel

module

Module

is a type used in conjunction with deflate-with. It controls the compression level.

The constructors are NoCompression, BestSpeed, BestCompression, and DefaultCompression, which is, well, the default.

deflate

defn

(Fn [(Ref String a)] (Result ZLib.ZBytes String)) 

                        (deflate s)

takes a string s and returns a Result.

The Result will be a Success containing the deflated bytes if all goes well, and an Error returning an error message otherwise.

It is equivalent to calling deflate-with with (ZLevel.DefaultCompression).

deflate-bytes

defn

(Fn [(Ref (Array Byte) a)] (Result (Array Byte) String)) 

                        (deflate-bytes b)

takes bytes b and returns a Result.

The Result will be a Success containing the deflated bytes if all goes well, and an Error returning an error message otherwise.

It is equivalent to calling deflate-bytes-with with (ZLevel.DefaultCompression).

deflate-bytes-with

defn

(Fn [(Ref (Array Byte) a), ZLib.ZLevel] (Result (Array Byte) String)) 

                        (deflate-bytes-with b level)

takes bytes b, a ZLevel level and returns a Result.

The Result will be a Success containing the deflated bytes if all goes well, and an Error returning an error message otherwise.

Unlike deflate-with, it compresses all of b, NUL bytes included, and hands you the compressed bytes.

deflate-with

defn

(Fn [(Ref String a), ZLib.ZLevel] (Result ZLib.ZBytes String)) 

                        (deflate-with s level)

takes a string s, a ZLevel level and returns a Result.

The Result will be a Success containing the deflated bytes if all goes well, and an Error returning an error message otherwise.

inflate

defn

(Fn [ZLib.ZBytes] (Result String String)) 

                        (inflate s)

takes a bytes object s and returns a Result.

The Result will be a Success containing the inflated string if all goes well, and an Error returning an error message otherwise.

inflate-bytes

defn

(Fn [(Array Byte)] (Result (Array Byte) String)) 

                        (inflate-bytes b)

takes compressed bytes b and returns a Result.

The Result will be a Success containing the inflated bytes if all goes well, and an Error returning an error message otherwise.

Unlike inflate, it can decompress payloads that contain NUL bytes.