Codec.Zlib
Contents
Description
This is a middle-level wrapper around the zlib C API. It allows you to work fully with bytestrings and not touch the FFI at all, but is still low-level enough to allow you to implement high-level abstractions such as enumerators. Significantly, it does not use lazy IO.
You'll probably need to reference the docs a bit to understand the WindowBits parameters below, but a basic rule of thumb is 15 is for zlib compression, and 31 for gzip compression.
- data Inflate
- initInflate :: WindowBits -> IO Inflate
- withInflateInput :: Inflate -> ByteString -> (IO (Maybe ByteString) -> IO a) -> IO a
- finishInflate :: Inflate -> IO ByteString
- data Deflate
- initDeflate :: Int -> WindowBits -> IO Deflate
- withDeflateInput :: Deflate -> ByteString -> (IO (Maybe ByteString) -> IO a) -> IO a
- finishDeflate :: Deflate -> (IO (Maybe ByteString) -> IO a) -> IO a
- data WindowBits = WindowBits Int
- defaultWindowBits :: WindowBits
- data ZlibException = ZlibException Int
Inflate
data Inflate
The state of an inflation (eg, decompression) process. All allocated memory is automatically reclaimed by the garbage collector.
initInflate :: WindowBits -> IO Inflate
Initialize an inflation process with the given WindowBits. You will need
 to call withInflateInput to feed compressed data to this and
 finishInflate to extract the final chunk of decompressed data.
withInflateInput :: Inflate -> ByteString -> (IO (Maybe ByteString) -> IO a) -> IO a
Feed the given ByteString to the inflater. This function takes a
 function argument which takes a "popper". A popper is an IO action that
 will return the next bit of inflated data, returning Nothing when there is
 no more data to be popped.
Note that this function automatically buffers the output to
 defaultChunkSize, and therefore you won't get any data from the popper
 until that much decompressed data is available. After you have fed all of
 the compressed data to this function, you can extract your final chunk of
 decompressed data using finishInflate.
finishInflate :: Inflate -> IO ByteString
As explained in withInflateInput, inflation buffers your decompressed
 data. After you call withInflateInput with your last chunk of compressed
 data, you will likely have some data still sitting in the buffer. This
 function will return it to you.
Deflate
data Deflate
The state of a deflation (eg, compression) process. All allocated memory is automatically reclaimed by the garbage collector.
Arguments
| :: Int | Compression level | 
| -> WindowBits | |
| -> IO Deflate | 
Initialize a deflation process with the given compression level and
 WindowBits. You will need to call withDeflateInput to feed uncompressed
 data to this and finishDeflate to extract the final chunks of compressed
 data.
withDeflateInput :: Deflate -> ByteString -> (IO (Maybe ByteString) -> IO a) -> IO a
Feed the given ByteString to the deflater. This function takes a
 function argument which takes a "popper". A popper is an IO action that
 will return the next bit of deflated data, returning Nothing when there is
 no more data to be popped.
Note that this function automatically buffers the output to
 defaultChunkSize, and therefore you won't get any data from the popper
 until that much compressed data is available. After you have fed all of the
 decompressed data to this function, you can extract your final chunks of
 compressed data using finishDeflate.
finishDeflate :: Deflate -> (IO (Maybe ByteString) -> IO a) -> IO a
As explained in withDeflateInput, deflation buffers your compressed
 data. After you call withDeflateInput with your last chunk of decompressed
 data, we need to flush the rest of the data waiting to be deflated. This
 function takes a function parameter which accepts a "popper", just like
 withDeflateInput.
Data types
data WindowBits
This specifies the size of the compression window. Larger values of this parameter result in better compression at the expense of higher memory usage.
The compression window size is the value of the the window bits raised to
 the power 2. The window bits must be in the range 8..15 which corresponds
 to compression window sizes of 256b to 32Kb. The default is 15 which is also
 the maximum size.
The total amount of memory used depends on the window bits and the
 MemoryLevel. See the MemoryLevel for the details.
Constructors
| WindowBits Int | 
defaultWindowBits :: WindowBits
The default WindowBits is 15 which is also the maximum size.
data ZlibException
Exception that can be thrown from the FFI code. The parameter is the numerical error code from the zlib library. Quoting the zlib.h file directly:
- #define Z_OK 0
- #define Z_STREAM_END 1
- #define Z_NEED_DICT 2
- #define Z_ERRNO (-1)
- #define Z_STREAM_ERROR (-2)
- #define Z_DATA_ERROR (-3)
- #define Z_MEM_ERROR (-4)
- #define Z_BUF_ERROR (-5)
- #define Z_VERSION_ERROR (-6)
Constructors
| ZlibException Int |