-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Compression and decompression in the gzip and zlib formats
--   
--   This package provides a pure interface for compressing and
--   decompressing streams of data represented as lazy <a>ByteString</a>s.
--   It uses the zlib C library so it has high performance. It supports the
--   "zlib", "gzip" and "raw" compression formats.
--   
--   It provides a convenient high level API suitable for most tasks and
--   for the few cases where more control is needed it provides access to
--   the full zlib feature set.
@package zlib
@version 0.5.4.1


-- | Pure stream based interface to lower level zlib wrapper
module Codec.Compression.Zlib.Internal

-- | Compress a data stream.
--   
--   There are no expected error conditions. All input data streams are
--   valid. It is possible for unexpected errors to occur, such as running
--   out of memory, or finding the wrong version of the zlib C library,
--   these are thrown as exceptions.
compress :: Format -> CompressParams -> ByteString -> ByteString

-- | The full set of parameters for compression. The defaults are
--   <a>defaultCompressParams</a>.
--   
--   The <a>compressBufferSize</a> is the size of the first output buffer
--   containing the compressed data. If you know an approximate upper bound
--   on the size of the compressed data then setting this parameter can
--   save memory. The default compression output buffer size is
--   <tt>16k</tt>. If your extimate is wrong it does not matter too much,
--   the default buffer size will be used for the remaining chunks.
data CompressParams
CompressParams :: !CompressionLevel -> !Method -> !WindowBits -> !MemoryLevel -> !CompressionStrategy -> !Int -> Maybe ByteString -> CompressParams
compressLevel :: CompressParams -> !CompressionLevel
compressMethod :: CompressParams -> !Method
compressWindowBits :: CompressParams -> !WindowBits
compressMemoryLevel :: CompressParams -> !MemoryLevel
compressStrategy :: CompressParams -> !CompressionStrategy
compressBufferSize :: CompressParams -> !Int
compressDictionary :: CompressParams -> Maybe ByteString

-- | The default set of parameters for compression. This is typically used
--   with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultCompressParams :: CompressParams

-- | Decompress a data stream.
--   
--   It will throw an exception if any error is encountered in the input
--   data. If you need more control over error handling then use
--   <a>decompressWithErrors</a>.
decompress :: Format -> DecompressParams -> ByteString -> ByteString

-- | The full set of parameters for decompression. The defaults are
--   <a>defaultDecompressParams</a>.
--   
--   The <a>decompressBufferSize</a> is the size of the first output
--   buffer, containing the uncompressed data. If you know an exact or
--   approximate upper bound on the size of the decompressed data then
--   setting this parameter can save memory. The default decompression
--   output buffer size is <tt>32k</tt>. If your extimate is wrong it does
--   not matter too much, the default buffer size will be used for the
--   remaining chunks.
--   
--   One particular use case for setting the <a>decompressBufferSize</a> is
--   if you know the exact size of the decompressed data and want to
--   produce a strict <a>ByteString</a>. The compression and deccompression
--   functions use lazy <a>ByteString</a>s but if you set the
--   <a>decompressBufferSize</a> correctly then you can generate a lazy
--   <a>ByteString</a> with exactly one chunk, which can be converted to a
--   strict <a>ByteString</a> in <tt>O(1)</tt> time using <tt><a>concat</a>
--   . <a>toChunks</a></tt>.
data DecompressParams
DecompressParams :: !WindowBits -> !Int -> Maybe ByteString -> DecompressParams
decompressWindowBits :: DecompressParams -> !WindowBits
decompressBufferSize :: DecompressParams -> !Int
decompressDictionary :: DecompressParams -> Maybe ByteString

-- | The default set of parameters for decompression. This is typically
--   used with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultDecompressParams :: DecompressParams

-- | The format used for compression or decompression. There are three
--   variations.
data Format

-- | <i>Deprecated: Use gzipFormat. Format constructors will be hidden in
--   version 0.7</i>
GZip :: Format

-- | <i>Deprecated: Use zlibFormat. Format constructors will be hidden in
--   version 0.7</i>
Zlib :: Format

-- | <i>Deprecated: Use rawFormat. Format constructors will be hidden in
--   version 0.7</i>
Raw :: Format

-- | <i>Deprecated: Use gzipOrZlibFormat. Format constructors will be
--   hidden in version 0.7</i>
GZipOrZlib :: Format

-- | The gzip format uses a header with a checksum and some optional
--   meta-data about the compressed file. It is intended primarily for
--   compressing individual files but is also sometimes used for network
--   protocols such as HTTP. The format is described in detail in RFC #1952
--   <a>http://www.ietf.org/rfc/rfc1952.txt</a>
gzipFormat :: Format

-- | The zlib format uses a minimal header with a checksum but no other
--   meta-data. It is especially designed for use in network protocols. The
--   format is described in detail in RFC #1950
--   <a>http://www.ietf.org/rfc/rfc1950.txt</a>
zlibFormat :: Format

-- | The 'raw' format is just the compressed data stream without any
--   additional header, meta-data or data-integrity checksum. The format is
--   described in detail in RFC #1951
--   <a>http://www.ietf.org/rfc/rfc1951.txt</a>
rawFormat :: Format

-- | This is not a format as such. It enabled zlib or gzip decoding with
--   automatic header detection. This only makes sense for decompression.
gzipOrZlibFormat :: Format

-- | The compression level parameter controls the amount of compression.
--   This is a trade-off between the amount of compression and the time
--   required to do the compression.
data CompressionLevel

-- | <i>Deprecated: Use defaultCompression. CompressionLevel constructors
--   will be hidden in version 0.7</i>
DefaultCompression :: CompressionLevel

-- | <i>Deprecated: Use noCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
NoCompression :: CompressionLevel

-- | <i>Deprecated: Use bestSpeed. CompressionLevel constructors will be
--   hidden in version 0.7</i>
BestSpeed :: CompressionLevel

-- | <i>Deprecated: Use bestCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
BestCompression :: CompressionLevel
CompressionLevel :: Int -> CompressionLevel

-- | The default compression level is 6 (that is, biased towards higher
--   compression at expense of speed).
defaultCompression :: CompressionLevel

-- | No compression, just a block copy.
noCompression :: CompressionLevel

-- | The fastest compression method (less compression)
bestSpeed :: CompressionLevel

-- | The slowest compression method (best compression).
bestCompression :: CompressionLevel

-- | A specific compression level between 0 and 9.
compressionLevel :: Int -> CompressionLevel

-- | The compression method
data Method

-- | <i>Deprecated: Use deflateMethod. Method constructors will be hidden
--   in version 0.7</i>
Deflated :: Method

-- | 'Deflate' is the only method supported in this version of zlib. Indeed
--   it is likely to be the only method that ever will be supported.
deflateMethod :: Method

-- | 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 <tt>8..15</tt>
--   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
--   <a>MemoryLevel</a>. See the <a>MemoryLevel</a> for the details.
data WindowBits
WindowBits :: Int -> WindowBits

-- | <i>Deprecated: Use defaultWindowBits. WindowBits constructors will be
--   hidden in version 0.7</i>
DefaultWindowBits :: WindowBits

-- | The default <a>WindowBits</a> is 15 which is also the maximum size.
defaultWindowBits :: WindowBits

-- | A specific compression window size, specified in bits in the range
--   <tt>8..15</tt>
windowBits :: Int -> WindowBits

-- | The <a>MemoryLevel</a> parameter specifies how much memory should be
--   allocated for the internal compression state. It is a tradoff between
--   memory usage, compression ratio and compression speed. Using more
--   memory allows faster compression and a better compression ratio.
--   
--   The total amount of memory used for compression depends on the
--   <a>WindowBits</a> and the <a>MemoryLevel</a>. For decompression it
--   depends only on the <a>WindowBits</a>. The totals are given by the
--   functions:
--   
--   <pre>
--   compressTotal windowBits memLevel = 4 * 2^windowBits + 512 * 2^memLevel
--   decompressTotal windowBits = 2^windowBits
--   </pre>
--   
--   For example, for compression with the default <tt>windowBits = 15</tt>
--   and <tt>memLevel = 8</tt> uses <tt>256Kb</tt>. So for example a
--   network server with 100 concurrent compressed streams would use
--   <tt>25Mb</tt>. The memory per stream can be halved (at the cost of
--   somewhat degraded and slower compressionby) by reducing the
--   <tt>windowBits</tt> and <tt>memLevel</tt> by one.
--   
--   Decompression takes less memory, the default <tt>windowBits = 15</tt>
--   corresponds to just <tt>32Kb</tt>.
data MemoryLevel

-- | <i>Deprecated: Use defaultMemoryLevel. MemoryLevel constructors will
--   be hidden in version 0.7</i>
DefaultMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use minMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MinMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use maxMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MaxMemoryLevel :: MemoryLevel
MemoryLevel :: Int -> MemoryLevel

-- | The default memory level. (Equivalent to <tt><a>memoryLevel</a>
--   8</tt>)
defaultMemoryLevel :: MemoryLevel

-- | Use minimum memory. This is slow and reduces the compression ratio.
--   (Equivalent to <tt><a>memoryLevel</a> 1</tt>)
minMemoryLevel :: MemoryLevel

-- | Use maximum memory for optimal compression speed. (Equivalent to
--   <tt><a>memoryLevel</a> 9</tt>)
maxMemoryLevel :: MemoryLevel

-- | A specific level in the range <tt>1..9</tt>
memoryLevel :: Int -> MemoryLevel

-- | The strategy parameter is used to tune the compression algorithm.
--   
--   The strategy parameter only affects the compression ratio but not the
--   correctness of the compressed output even if it is not set
--   appropriately.
data CompressionStrategy

-- | <i>Deprecated: Use defaultStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
DefaultStrategy :: CompressionStrategy

-- | <i>Deprecated: Use filteredStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
Filtered :: CompressionStrategy

-- | <i>Deprecated: Use huffmanOnlyStrategy. CompressionStrategy
--   constructors will be hidden in version 0.7</i>
HuffmanOnly :: CompressionStrategy

-- | Use this default compression strategy for normal data.
defaultStrategy :: CompressionStrategy

-- | Use the filtered compression strategy for data produced by a filter
--   (or predictor). Filtered data consists mostly of small values with a
--   somewhat random distribution. In this case, the compression algorithm
--   is tuned to compress them better. The effect of this strategy is to
--   force more Huffman coding and less string matching; it is somewhat
--   intermediate between <tt>defaultCompressionStrategy</tt> and
--   <tt>huffmanOnlyCompressionStrategy</tt>.
filteredStrategy :: CompressionStrategy

-- | Use the Huffman-only compression strategy to force Huffman encoding
--   only (no string match).
huffmanOnlyStrategy :: CompressionStrategy

-- | Like <a>decompress</a> but returns a <a>DecompressStream</a> data
--   structure that contains an explicit representation of the error
--   conditions that one may encounter when decompressing.
--   
--   Note that in addition to errors in the input data, it is possible for
--   other unexpected errors to occur, such as out of memory, or finding
--   the wrong version of the zlib C library, these are still thrown as
--   exceptions (because representing them as data would make this function
--   impure).
decompressWithErrors :: Format -> DecompressParams -> ByteString -> DecompressStream

-- | A sequence of chunks of data produced from decompression.
--   
--   The difference from a simple list is that it contains a representation
--   of errors as data rather than as exceptions. This allows you to handle
--   error conditions explicitly.
data DecompressStream
StreamEnd :: DecompressStream
StreamChunk :: ByteString -> DecompressStream -> DecompressStream

-- | An error code and a human readable error message.
StreamError :: DecompressError -> String -> DecompressStream

-- | The possible error cases when decompressing a stream.
data DecompressError

-- | The compressed data stream ended prematurely. This may happen if the
--   input data stream was truncated.
TruncatedInput :: DecompressError

-- | It is possible to do zlib compression with a custom dictionary. This
--   allows slightly higher compression ratios for short files. However
--   such compressed streams require the same dictionary when
--   decompressing. This error is for when we encounter a compressed stream
--   that needs a dictionary, and it's not provided.
DictionaryRequired :: DecompressError

-- | If the compressed data stream is corrupted in any way then you will
--   get this error, for example if the input data just isn't a compressed
--   zlib data stream. In particular if the data checksum turns out to be
--   wrong then you will get all the decompressed data but this error at
--   the end, instead of the normal sucessful <a>StreamEnd</a>.
DataError :: DecompressError

-- | Fold an <tt>DecompressionStream</tt>. Just like <a>foldr</a> but with
--   an extra error case. For example to convert to a list and translate
--   the errors into exceptions:
--   
--   <pre>
--   foldDecompressStream (:) [] (\code msg -&gt; error msg)
--   </pre>
foldDecompressStream :: (ByteString -> a -> a) -> a -> (DecompressError -> String -> a) -> DecompressStream -> a

-- | Convert a <a>DecompressStream</a> to a lazy <tt>ByteString</tt>. If
--   any decompression errors are encountered then they are thrown as
--   exceptions.
--   
--   This is a special case of <a>foldDecompressStream</a>.
fromDecompressStream :: DecompressStream -> ByteString


-- | Compression and decompression of data streams in the raw deflate
--   format.
--   
--   The format is described in detail in RFC #1951:
--   <a>http://www.ietf.org/rfc/rfc1951.txt</a>
--   
--   See also the zlib home page: <a>http://zlib.net/</a>
module Codec.Compression.Zlib.Raw
compress :: ByteString -> ByteString
decompress :: ByteString -> ByteString
compressWith :: CompressParams -> ByteString -> ByteString
decompressWith :: DecompressParams -> ByteString -> ByteString

-- | The full set of parameters for compression. The defaults are
--   <a>defaultCompressParams</a>.
--   
--   The <a>compressBufferSize</a> is the size of the first output buffer
--   containing the compressed data. If you know an approximate upper bound
--   on the size of the compressed data then setting this parameter can
--   save memory. The default compression output buffer size is
--   <tt>16k</tt>. If your extimate is wrong it does not matter too much,
--   the default buffer size will be used for the remaining chunks.
data CompressParams
CompressParams :: !CompressionLevel -> !Method -> !WindowBits -> !MemoryLevel -> !CompressionStrategy -> !Int -> Maybe ByteString -> CompressParams
compressLevel :: CompressParams -> !CompressionLevel
compressMethod :: CompressParams -> !Method
compressWindowBits :: CompressParams -> !WindowBits
compressMemoryLevel :: CompressParams -> !MemoryLevel
compressStrategy :: CompressParams -> !CompressionStrategy
compressBufferSize :: CompressParams -> !Int
compressDictionary :: CompressParams -> Maybe ByteString

-- | The default set of parameters for compression. This is typically used
--   with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultCompressParams :: CompressParams

-- | The full set of parameters for decompression. The defaults are
--   <a>defaultDecompressParams</a>.
--   
--   The <a>decompressBufferSize</a> is the size of the first output
--   buffer, containing the uncompressed data. If you know an exact or
--   approximate upper bound on the size of the decompressed data then
--   setting this parameter can save memory. The default decompression
--   output buffer size is <tt>32k</tt>. If your extimate is wrong it does
--   not matter too much, the default buffer size will be used for the
--   remaining chunks.
--   
--   One particular use case for setting the <a>decompressBufferSize</a> is
--   if you know the exact size of the decompressed data and want to
--   produce a strict <a>ByteString</a>. The compression and deccompression
--   functions use lazy <a>ByteString</a>s but if you set the
--   <a>decompressBufferSize</a> correctly then you can generate a lazy
--   <a>ByteString</a> with exactly one chunk, which can be converted to a
--   strict <a>ByteString</a> in <tt>O(1)</tt> time using <tt><a>concat</a>
--   . <a>toChunks</a></tt>.
data DecompressParams
DecompressParams :: !WindowBits -> !Int -> Maybe ByteString -> DecompressParams
decompressWindowBits :: DecompressParams -> !WindowBits
decompressBufferSize :: DecompressParams -> !Int
decompressDictionary :: DecompressParams -> Maybe ByteString

-- | The default set of parameters for decompression. This is typically
--   used with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultDecompressParams :: DecompressParams

-- | The compression level parameter controls the amount of compression.
--   This is a trade-off between the amount of compression and the time
--   required to do the compression.
data CompressionLevel

-- | <i>Deprecated: Use defaultCompression. CompressionLevel constructors
--   will be hidden in version 0.7</i>
DefaultCompression :: CompressionLevel

-- | <i>Deprecated: Use noCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
NoCompression :: CompressionLevel

-- | <i>Deprecated: Use bestSpeed. CompressionLevel constructors will be
--   hidden in version 0.7</i>
BestSpeed :: CompressionLevel

-- | <i>Deprecated: Use bestCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
BestCompression :: CompressionLevel
CompressionLevel :: Int -> CompressionLevel

-- | The default compression level is 6 (that is, biased towards higher
--   compression at expense of speed).
defaultCompression :: CompressionLevel

-- | No compression, just a block copy.
noCompression :: CompressionLevel

-- | The fastest compression method (less compression)
bestSpeed :: CompressionLevel

-- | The slowest compression method (best compression).
bestCompression :: CompressionLevel

-- | A specific compression level between 0 and 9.
compressionLevel :: Int -> CompressionLevel

-- | The compression method
data Method

-- | <i>Deprecated: Use deflateMethod. Method constructors will be hidden
--   in version 0.7</i>
Deflated :: Method

-- | 'Deflate' is the only method supported in this version of zlib. Indeed
--   it is likely to be the only method that ever will be supported.
deflateMethod :: Method

-- | 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 <tt>8..15</tt>
--   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
--   <a>MemoryLevel</a>. See the <a>MemoryLevel</a> for the details.
data WindowBits
WindowBits :: Int -> WindowBits

-- | <i>Deprecated: Use defaultWindowBits. WindowBits constructors will be
--   hidden in version 0.7</i>
DefaultWindowBits :: WindowBits

-- | The default <a>WindowBits</a> is 15 which is also the maximum size.
defaultWindowBits :: WindowBits

-- | A specific compression window size, specified in bits in the range
--   <tt>8..15</tt>
windowBits :: Int -> WindowBits

-- | The <a>MemoryLevel</a> parameter specifies how much memory should be
--   allocated for the internal compression state. It is a tradoff between
--   memory usage, compression ratio and compression speed. Using more
--   memory allows faster compression and a better compression ratio.
--   
--   The total amount of memory used for compression depends on the
--   <a>WindowBits</a> and the <a>MemoryLevel</a>. For decompression it
--   depends only on the <a>WindowBits</a>. The totals are given by the
--   functions:
--   
--   <pre>
--   compressTotal windowBits memLevel = 4 * 2^windowBits + 512 * 2^memLevel
--   decompressTotal windowBits = 2^windowBits
--   </pre>
--   
--   For example, for compression with the default <tt>windowBits = 15</tt>
--   and <tt>memLevel = 8</tt> uses <tt>256Kb</tt>. So for example a
--   network server with 100 concurrent compressed streams would use
--   <tt>25Mb</tt>. The memory per stream can be halved (at the cost of
--   somewhat degraded and slower compressionby) by reducing the
--   <tt>windowBits</tt> and <tt>memLevel</tt> by one.
--   
--   Decompression takes less memory, the default <tt>windowBits = 15</tt>
--   corresponds to just <tt>32Kb</tt>.
data MemoryLevel

-- | <i>Deprecated: Use defaultMemoryLevel. MemoryLevel constructors will
--   be hidden in version 0.7</i>
DefaultMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use minMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MinMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use maxMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MaxMemoryLevel :: MemoryLevel
MemoryLevel :: Int -> MemoryLevel

-- | The default memory level. (Equivalent to <tt><a>memoryLevel</a>
--   8</tt>)
defaultMemoryLevel :: MemoryLevel

-- | Use minimum memory. This is slow and reduces the compression ratio.
--   (Equivalent to <tt><a>memoryLevel</a> 1</tt>)
minMemoryLevel :: MemoryLevel

-- | Use maximum memory for optimal compression speed. (Equivalent to
--   <tt><a>memoryLevel</a> 9</tt>)
maxMemoryLevel :: MemoryLevel

-- | A specific level in the range <tt>1..9</tt>
memoryLevel :: Int -> MemoryLevel

-- | The strategy parameter is used to tune the compression algorithm.
--   
--   The strategy parameter only affects the compression ratio but not the
--   correctness of the compressed output even if it is not set
--   appropriately.
data CompressionStrategy

-- | <i>Deprecated: Use defaultStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
DefaultStrategy :: CompressionStrategy

-- | <i>Deprecated: Use filteredStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
Filtered :: CompressionStrategy

-- | <i>Deprecated: Use huffmanOnlyStrategy. CompressionStrategy
--   constructors will be hidden in version 0.7</i>
HuffmanOnly :: CompressionStrategy

-- | Use this default compression strategy for normal data.
defaultStrategy :: CompressionStrategy

-- | Use the filtered compression strategy for data produced by a filter
--   (or predictor). Filtered data consists mostly of small values with a
--   somewhat random distribution. In this case, the compression algorithm
--   is tuned to compress them better. The effect of this strategy is to
--   force more Huffman coding and less string matching; it is somewhat
--   intermediate between <tt>defaultCompressionStrategy</tt> and
--   <tt>huffmanOnlyCompressionStrategy</tt>.
filteredStrategy :: CompressionStrategy

-- | Use the Huffman-only compression strategy to force Huffman encoding
--   only (no string match).
huffmanOnlyStrategy :: CompressionStrategy


-- | Compression and decompression of data streams in the zlib format.
--   
--   The format is described in detail in RFC #1950:
--   <a>http://www.ietf.org/rfc/rfc1950.txt</a>
--   
--   See also the zlib home page: <a>http://zlib.net/</a>
module Codec.Compression.Zlib

-- | Compress a stream of data into the zlib format.
--   
--   This uses the default compression parameters. In partiular it uses the
--   default compression level which favours a higher compression ratio
--   over compression speed, though it does not use the maximum compression
--   level.
--   
--   Use <a>compressWith</a> to adjust the compression level or other
--   compression parameters.
compress :: ByteString -> ByteString

-- | Decompress a stream of data in the zlib format.
--   
--   There are a number of errors that can occur. In each case an exception
--   will be thrown. The possible error conditions are:
--   
--   <ul>
--   <li>if the stream does not start with a valid gzip header</li>
--   <li>if the compressed stream is corrupted</li>
--   <li>if the compressed stream ends permaturely</li>
--   </ul>
--   
--   Note that the decompression is performed <i>lazily</i>. Errors in the
--   data stream may not be detected until the end of the stream is
--   demanded (since it is only at the end that the final checksum can be
--   checked). If this is important to you, you must make sure to consume
--   the whole decompressed stream before doing any IO action that depends
--   on it.
decompress :: ByteString -> ByteString

-- | Like <a>compress</a> but with the ability to specify various
--   compression parameters. Typical usage:
--   
--   <pre>
--   compressWith defaultCompressParams { ... }
--   </pre>
--   
--   In particular you can set the compression level:
--   
--   <pre>
--   compressWith defaultCompressParams { compressLevel = BestCompression }
--   </pre>
compressWith :: CompressParams -> ByteString -> ByteString

-- | Like <a>decompress</a> but with the ability to specify various
--   decompression parameters. Typical usage:
--   
--   <pre>
--   decompressWith defaultCompressParams { ... }
--   </pre>
decompressWith :: DecompressParams -> ByteString -> ByteString

-- | The full set of parameters for compression. The defaults are
--   <a>defaultCompressParams</a>.
--   
--   The <a>compressBufferSize</a> is the size of the first output buffer
--   containing the compressed data. If you know an approximate upper bound
--   on the size of the compressed data then setting this parameter can
--   save memory. The default compression output buffer size is
--   <tt>16k</tt>. If your extimate is wrong it does not matter too much,
--   the default buffer size will be used for the remaining chunks.
data CompressParams
CompressParams :: !CompressionLevel -> !Method -> !WindowBits -> !MemoryLevel -> !CompressionStrategy -> !Int -> Maybe ByteString -> CompressParams
compressLevel :: CompressParams -> !CompressionLevel
compressMethod :: CompressParams -> !Method
compressWindowBits :: CompressParams -> !WindowBits
compressMemoryLevel :: CompressParams -> !MemoryLevel
compressStrategy :: CompressParams -> !CompressionStrategy
compressBufferSize :: CompressParams -> !Int
compressDictionary :: CompressParams -> Maybe ByteString

-- | The default set of parameters for compression. This is typically used
--   with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultCompressParams :: CompressParams

-- | The full set of parameters for decompression. The defaults are
--   <a>defaultDecompressParams</a>.
--   
--   The <a>decompressBufferSize</a> is the size of the first output
--   buffer, containing the uncompressed data. If you know an exact or
--   approximate upper bound on the size of the decompressed data then
--   setting this parameter can save memory. The default decompression
--   output buffer size is <tt>32k</tt>. If your extimate is wrong it does
--   not matter too much, the default buffer size will be used for the
--   remaining chunks.
--   
--   One particular use case for setting the <a>decompressBufferSize</a> is
--   if you know the exact size of the decompressed data and want to
--   produce a strict <a>ByteString</a>. The compression and deccompression
--   functions use lazy <a>ByteString</a>s but if you set the
--   <a>decompressBufferSize</a> correctly then you can generate a lazy
--   <a>ByteString</a> with exactly one chunk, which can be converted to a
--   strict <a>ByteString</a> in <tt>O(1)</tt> time using <tt><a>concat</a>
--   . <a>toChunks</a></tt>.
data DecompressParams
DecompressParams :: !WindowBits -> !Int -> Maybe ByteString -> DecompressParams
decompressWindowBits :: DecompressParams -> !WindowBits
decompressBufferSize :: DecompressParams -> !Int
decompressDictionary :: DecompressParams -> Maybe ByteString

-- | The default set of parameters for decompression. This is typically
--   used with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultDecompressParams :: DecompressParams

-- | The compression level parameter controls the amount of compression.
--   This is a trade-off between the amount of compression and the time
--   required to do the compression.
data CompressionLevel

-- | <i>Deprecated: Use defaultCompression. CompressionLevel constructors
--   will be hidden in version 0.7</i>
DefaultCompression :: CompressionLevel

-- | <i>Deprecated: Use noCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
NoCompression :: CompressionLevel

-- | <i>Deprecated: Use bestSpeed. CompressionLevel constructors will be
--   hidden in version 0.7</i>
BestSpeed :: CompressionLevel

-- | <i>Deprecated: Use bestCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
BestCompression :: CompressionLevel
CompressionLevel :: Int -> CompressionLevel

-- | The default compression level is 6 (that is, biased towards higher
--   compression at expense of speed).
defaultCompression :: CompressionLevel

-- | No compression, just a block copy.
noCompression :: CompressionLevel

-- | The fastest compression method (less compression)
bestSpeed :: CompressionLevel

-- | The slowest compression method (best compression).
bestCompression :: CompressionLevel

-- | A specific compression level between 0 and 9.
compressionLevel :: Int -> CompressionLevel

-- | The compression method
data Method

-- | <i>Deprecated: Use deflateMethod. Method constructors will be hidden
--   in version 0.7</i>
Deflated :: Method

-- | 'Deflate' is the only method supported in this version of zlib. Indeed
--   it is likely to be the only method that ever will be supported.
deflateMethod :: Method

-- | 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 <tt>8..15</tt>
--   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
--   <a>MemoryLevel</a>. See the <a>MemoryLevel</a> for the details.
data WindowBits
WindowBits :: Int -> WindowBits

-- | <i>Deprecated: Use defaultWindowBits. WindowBits constructors will be
--   hidden in version 0.7</i>
DefaultWindowBits :: WindowBits

-- | The default <a>WindowBits</a> is 15 which is also the maximum size.
defaultWindowBits :: WindowBits

-- | A specific compression window size, specified in bits in the range
--   <tt>8..15</tt>
windowBits :: Int -> WindowBits

-- | The <a>MemoryLevel</a> parameter specifies how much memory should be
--   allocated for the internal compression state. It is a tradoff between
--   memory usage, compression ratio and compression speed. Using more
--   memory allows faster compression and a better compression ratio.
--   
--   The total amount of memory used for compression depends on the
--   <a>WindowBits</a> and the <a>MemoryLevel</a>. For decompression it
--   depends only on the <a>WindowBits</a>. The totals are given by the
--   functions:
--   
--   <pre>
--   compressTotal windowBits memLevel = 4 * 2^windowBits + 512 * 2^memLevel
--   decompressTotal windowBits = 2^windowBits
--   </pre>
--   
--   For example, for compression with the default <tt>windowBits = 15</tt>
--   and <tt>memLevel = 8</tt> uses <tt>256Kb</tt>. So for example a
--   network server with 100 concurrent compressed streams would use
--   <tt>25Mb</tt>. The memory per stream can be halved (at the cost of
--   somewhat degraded and slower compressionby) by reducing the
--   <tt>windowBits</tt> and <tt>memLevel</tt> by one.
--   
--   Decompression takes less memory, the default <tt>windowBits = 15</tt>
--   corresponds to just <tt>32Kb</tt>.
data MemoryLevel

-- | <i>Deprecated: Use defaultMemoryLevel. MemoryLevel constructors will
--   be hidden in version 0.7</i>
DefaultMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use minMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MinMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use maxMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MaxMemoryLevel :: MemoryLevel
MemoryLevel :: Int -> MemoryLevel

-- | The default memory level. (Equivalent to <tt><a>memoryLevel</a>
--   8</tt>)
defaultMemoryLevel :: MemoryLevel

-- | Use minimum memory. This is slow and reduces the compression ratio.
--   (Equivalent to <tt><a>memoryLevel</a> 1</tt>)
minMemoryLevel :: MemoryLevel

-- | Use maximum memory for optimal compression speed. (Equivalent to
--   <tt><a>memoryLevel</a> 9</tt>)
maxMemoryLevel :: MemoryLevel

-- | A specific level in the range <tt>1..9</tt>
memoryLevel :: Int -> MemoryLevel

-- | The strategy parameter is used to tune the compression algorithm.
--   
--   The strategy parameter only affects the compression ratio but not the
--   correctness of the compressed output even if it is not set
--   appropriately.
data CompressionStrategy

-- | <i>Deprecated: Use defaultStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
DefaultStrategy :: CompressionStrategy

-- | <i>Deprecated: Use filteredStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
Filtered :: CompressionStrategy

-- | <i>Deprecated: Use huffmanOnlyStrategy. CompressionStrategy
--   constructors will be hidden in version 0.7</i>
HuffmanOnly :: CompressionStrategy

-- | Use this default compression strategy for normal data.
defaultStrategy :: CompressionStrategy

-- | Use the filtered compression strategy for data produced by a filter
--   (or predictor). Filtered data consists mostly of small values with a
--   somewhat random distribution. In this case, the compression algorithm
--   is tuned to compress them better. The effect of this strategy is to
--   force more Huffman coding and less string matching; it is somewhat
--   intermediate between <tt>defaultCompressionStrategy</tt> and
--   <tt>huffmanOnlyCompressionStrategy</tt>.
filteredStrategy :: CompressionStrategy

-- | Use the Huffman-only compression strategy to force Huffman encoding
--   only (no string match).
huffmanOnlyStrategy :: CompressionStrategy


-- | Compression and decompression of data streams in the gzip format.
--   
--   The format is described in detail in RFC #1952:
--   <a>http://www.ietf.org/rfc/rfc1952.txt</a>
--   
--   See also the zlib home page: <a>http://zlib.net/</a>
module Codec.Compression.GZip

-- | Compress a stream of data into the gzip format.
--   
--   This uses the default compression parameters. In partiular it uses the
--   default compression level which favours a higher compression ratio
--   over compression speed, though it does not use the maximum compression
--   level.
--   
--   Use <a>compressWith</a> to adjust the compression level or other
--   compression parameters.
compress :: ByteString -> ByteString

-- | Decompress a stream of data in the gzip format.
--   
--   There are a number of errors that can occur. In each case an exception
--   will be thrown. The possible error conditions are:
--   
--   <ul>
--   <li>if the stream does not start with a valid gzip header</li>
--   <li>if the compressed stream is corrupted</li>
--   <li>if the compressed stream ends permaturely</li>
--   </ul>
--   
--   Note that the decompression is performed <i>lazily</i>. Errors in the
--   data stream may not be detected until the end of the stream is
--   demanded (since it is only at the end that the final checksum can be
--   checked). If this is important to you, you must make sure to consume
--   the whole decompressed stream before doing any IO action that depends
--   on it.
decompress :: ByteString -> ByteString

-- | Like <a>compress</a> but with the ability to specify various
--   compression parameters. Typical usage:
--   
--   <pre>
--   compressWith defaultCompressParams { ... }
--   </pre>
--   
--   In particular you can set the compression level:
--   
--   <pre>
--   compressWith defaultCompressParams { compressLevel = BestCompression }
--   </pre>
compressWith :: CompressParams -> ByteString -> ByteString

-- | Like <a>decompress</a> but with the ability to specify various
--   decompression parameters. Typical usage:
--   
--   <pre>
--   decompressWith defaultCompressParams { ... }
--   </pre>
decompressWith :: DecompressParams -> ByteString -> ByteString

-- | The full set of parameters for compression. The defaults are
--   <a>defaultCompressParams</a>.
--   
--   The <a>compressBufferSize</a> is the size of the first output buffer
--   containing the compressed data. If you know an approximate upper bound
--   on the size of the compressed data then setting this parameter can
--   save memory. The default compression output buffer size is
--   <tt>16k</tt>. If your extimate is wrong it does not matter too much,
--   the default buffer size will be used for the remaining chunks.
data CompressParams
CompressParams :: !CompressionLevel -> !Method -> !WindowBits -> !MemoryLevel -> !CompressionStrategy -> !Int -> Maybe ByteString -> CompressParams
compressLevel :: CompressParams -> !CompressionLevel
compressMethod :: CompressParams -> !Method
compressWindowBits :: CompressParams -> !WindowBits
compressMemoryLevel :: CompressParams -> !MemoryLevel
compressStrategy :: CompressParams -> !CompressionStrategy
compressBufferSize :: CompressParams -> !Int
compressDictionary :: CompressParams -> Maybe ByteString

-- | The default set of parameters for compression. This is typically used
--   with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultCompressParams :: CompressParams

-- | The full set of parameters for decompression. The defaults are
--   <a>defaultDecompressParams</a>.
--   
--   The <a>decompressBufferSize</a> is the size of the first output
--   buffer, containing the uncompressed data. If you know an exact or
--   approximate upper bound on the size of the decompressed data then
--   setting this parameter can save memory. The default decompression
--   output buffer size is <tt>32k</tt>. If your extimate is wrong it does
--   not matter too much, the default buffer size will be used for the
--   remaining chunks.
--   
--   One particular use case for setting the <a>decompressBufferSize</a> is
--   if you know the exact size of the decompressed data and want to
--   produce a strict <a>ByteString</a>. The compression and deccompression
--   functions use lazy <a>ByteString</a>s but if you set the
--   <a>decompressBufferSize</a> correctly then you can generate a lazy
--   <a>ByteString</a> with exactly one chunk, which can be converted to a
--   strict <a>ByteString</a> in <tt>O(1)</tt> time using <tt><a>concat</a>
--   . <a>toChunks</a></tt>.
data DecompressParams
DecompressParams :: !WindowBits -> !Int -> Maybe ByteString -> DecompressParams
decompressWindowBits :: DecompressParams -> !WindowBits
decompressBufferSize :: DecompressParams -> !Int
decompressDictionary :: DecompressParams -> Maybe ByteString

-- | The default set of parameters for decompression. This is typically
--   used with the <tt>compressWith</tt> function with specific parameters
--   overridden.
defaultDecompressParams :: DecompressParams

-- | The compression level parameter controls the amount of compression.
--   This is a trade-off between the amount of compression and the time
--   required to do the compression.
data CompressionLevel

-- | <i>Deprecated: Use defaultCompression. CompressionLevel constructors
--   will be hidden in version 0.7</i>
DefaultCompression :: CompressionLevel

-- | <i>Deprecated: Use noCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
NoCompression :: CompressionLevel

-- | <i>Deprecated: Use bestSpeed. CompressionLevel constructors will be
--   hidden in version 0.7</i>
BestSpeed :: CompressionLevel

-- | <i>Deprecated: Use bestCompression. CompressionLevel constructors will
--   be hidden in version 0.7</i>
BestCompression :: CompressionLevel
CompressionLevel :: Int -> CompressionLevel

-- | The default compression level is 6 (that is, biased towards higher
--   compression at expense of speed).
defaultCompression :: CompressionLevel

-- | No compression, just a block copy.
noCompression :: CompressionLevel

-- | The fastest compression method (less compression)
bestSpeed :: CompressionLevel

-- | The slowest compression method (best compression).
bestCompression :: CompressionLevel

-- | A specific compression level between 0 and 9.
compressionLevel :: Int -> CompressionLevel

-- | The compression method
data Method

-- | <i>Deprecated: Use deflateMethod. Method constructors will be hidden
--   in version 0.7</i>
Deflated :: Method

-- | 'Deflate' is the only method supported in this version of zlib. Indeed
--   it is likely to be the only method that ever will be supported.
deflateMethod :: Method

-- | 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 <tt>8..15</tt>
--   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
--   <a>MemoryLevel</a>. See the <a>MemoryLevel</a> for the details.
data WindowBits
WindowBits :: Int -> WindowBits

-- | <i>Deprecated: Use defaultWindowBits. WindowBits constructors will be
--   hidden in version 0.7</i>
DefaultWindowBits :: WindowBits

-- | The default <a>WindowBits</a> is 15 which is also the maximum size.
defaultWindowBits :: WindowBits

-- | A specific compression window size, specified in bits in the range
--   <tt>8..15</tt>
windowBits :: Int -> WindowBits

-- | The <a>MemoryLevel</a> parameter specifies how much memory should be
--   allocated for the internal compression state. It is a tradoff between
--   memory usage, compression ratio and compression speed. Using more
--   memory allows faster compression and a better compression ratio.
--   
--   The total amount of memory used for compression depends on the
--   <a>WindowBits</a> and the <a>MemoryLevel</a>. For decompression it
--   depends only on the <a>WindowBits</a>. The totals are given by the
--   functions:
--   
--   <pre>
--   compressTotal windowBits memLevel = 4 * 2^windowBits + 512 * 2^memLevel
--   decompressTotal windowBits = 2^windowBits
--   </pre>
--   
--   For example, for compression with the default <tt>windowBits = 15</tt>
--   and <tt>memLevel = 8</tt> uses <tt>256Kb</tt>. So for example a
--   network server with 100 concurrent compressed streams would use
--   <tt>25Mb</tt>. The memory per stream can be halved (at the cost of
--   somewhat degraded and slower compressionby) by reducing the
--   <tt>windowBits</tt> and <tt>memLevel</tt> by one.
--   
--   Decompression takes less memory, the default <tt>windowBits = 15</tt>
--   corresponds to just <tt>32Kb</tt>.
data MemoryLevel

-- | <i>Deprecated: Use defaultMemoryLevel. MemoryLevel constructors will
--   be hidden in version 0.7</i>
DefaultMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use minMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MinMemoryLevel :: MemoryLevel

-- | <i>Deprecated: Use maxMemoryLevel. MemoryLevel constructors will be
--   hidden in version 0.7</i>
MaxMemoryLevel :: MemoryLevel
MemoryLevel :: Int -> MemoryLevel

-- | The default memory level. (Equivalent to <tt><a>memoryLevel</a>
--   8</tt>)
defaultMemoryLevel :: MemoryLevel

-- | Use minimum memory. This is slow and reduces the compression ratio.
--   (Equivalent to <tt><a>memoryLevel</a> 1</tt>)
minMemoryLevel :: MemoryLevel

-- | Use maximum memory for optimal compression speed. (Equivalent to
--   <tt><a>memoryLevel</a> 9</tt>)
maxMemoryLevel :: MemoryLevel

-- | A specific level in the range <tt>1..9</tt>
memoryLevel :: Int -> MemoryLevel

-- | The strategy parameter is used to tune the compression algorithm.
--   
--   The strategy parameter only affects the compression ratio but not the
--   correctness of the compressed output even if it is not set
--   appropriately.
data CompressionStrategy

-- | <i>Deprecated: Use defaultStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
DefaultStrategy :: CompressionStrategy

-- | <i>Deprecated: Use filteredStrategy. CompressionStrategy constructors
--   will be hidden in version 0.7</i>
Filtered :: CompressionStrategy

-- | <i>Deprecated: Use huffmanOnlyStrategy. CompressionStrategy
--   constructors will be hidden in version 0.7</i>
HuffmanOnly :: CompressionStrategy

-- | Use this default compression strategy for normal data.
defaultStrategy :: CompressionStrategy

-- | Use the filtered compression strategy for data produced by a filter
--   (or predictor). Filtered data consists mostly of small values with a
--   somewhat random distribution. In this case, the compression algorithm
--   is tuned to compress them better. The effect of this strategy is to
--   force more Huffman coding and less string matching; it is somewhat
--   intermediate between <tt>defaultCompressionStrategy</tt> and
--   <tt>huffmanOnlyCompressionStrategy</tt>.
filteredStrategy :: CompressionStrategy

-- | Use the Huffman-only compression strategy to force Huffman encoding
--   only (no string match).
huffmanOnlyStrategy :: CompressionStrategy
