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


-- | Haskell bindings to the Zstandard compression algorithm
--   
--   A fast lossless compression algorithm, targeting real-time compression
--   scenarios at zlib-level and better compression ratios.
@package zstd
@version 0.1.2.0


-- | Low-level bindings to the native zstd compression library. These
--   bindings make almost no effort to provide any additional safety or
--   ease of use above that of the C library. Unless you have highly
--   specialized needs, you should use the streaming or base APIs instead.
--   
--   To correctly use the functions in this module, you must read the API
--   documentation in the zstd library's <tt>zstd.h</tt> include file. It
--   would also be wise to search elsewhere in this package for uses of the
--   functions you are interested in.
module Codec.Compression.Zstd.FFI

-- | Compress bytes from source buffer into destination buffer. The
--   destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
compress :: Ptr dst -> CSize -> Ptr src -> CSize -> CInt -> IO CSize

-- | Compute the maximum compressed size of given source buffer.
compressBound :: CSize -> IO CSize

-- | The maximum compression level supported by the library.
maxCLevel :: Int

-- | Decompress a buffer. The destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
decompress :: Ptr dst -> CSize -> Ptr src -> CSize -> IO CSize

-- | Returns the decompressed size of a compressed payload if known, 0
--   otherwise.
--   
--   To discover precisely why a result is 0, follow up with
--   <tt>getFrameParams</tt>.
getDecompressedSize :: Ptr src -> CSize -> IO CULLong

-- | An opaque compression context structure.
data CCtx

-- | Allocate a compression context.
createCCtx :: IO (Ptr CCtx)

-- | Free a compression context.
freeCCtx :: Ptr CCtx -> IO ()

-- | Free a compression context. For use by a finalizer.
p_freeCCtx :: FunPtr (Ptr CCtx -> IO ())

-- | Compress bytes from source buffer into destination buffer. The
--   destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
compressCCtx :: Ptr CCtx -> Ptr dst -> CSize -> Ptr src -> CSize -> CInt -> IO CSize

-- | An opaque decompression context structure.
data DCtx

-- | Allocate a decompression context.
createDCtx :: IO (Ptr DCtx)

-- | Free a decompression context.
freeDCtx :: Ptr DCtx -> IO ()

-- | Free a decompression context. For use by a finalizer.
p_freeDCtx :: FunPtr (Ptr DCtx -> IO ())

-- | Decompress a buffer. The destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
decompressDCtx :: Ptr DCtx -> Ptr dst -> CSize -> Ptr src -> CSize -> IO CSize

-- | Indicates whether a return value is an error code.
isError :: CSize -> Bool

-- | Gives the description associated with an error code.
getErrorName :: CSize -> String

-- | Check whether a <a>CSize</a> has an error encoded in it (yuck!), and
--   report success or failure more safely.
checkError :: IO CSize -> IO (Either String CSize)

-- | Check that an allocating operation is successful. If it fails, throw
--   an <a>IOError</a>.
checkAlloc :: String -> IO (Ptr a) -> IO (Ptr a)

-- | A context for streaming compression.
data CStream

-- | A context for streaming decompression.
data DStream

-- | A streaming buffer type. The type parameter statically indicates
--   whether the buffer is used to track an input or output buffer.
data Buffer io
Buffer :: {-# UNPACK #-} !Ptr a -> {-# UNPACK #-} !CSize -> {-# UNPACK #-} !CSize -> Buffer io

-- | Pointer to the start of the buffer. This can be set once by the
--   caller, and read by the streaming function.
[bufPtr] :: Buffer io -> {-# UNPACK #-} !Ptr a

-- | Size of the buffer (in bytes). This can be set once by the caller, and
--   is read by the streaming function.
[bufSize] :: Buffer io -> {-# UNPACK #-} !CSize

-- | Current offset into the buffer (in bytes). This must be initially set
--   to zero by the caller, and is updated by the streaming function.
[bufPos] :: Buffer io -> {-# UNPACK #-} !CSize

-- | A tag type to indicate that a <a>Buffer</a> is used for tracking
--   input.
data In

-- | A tag type to indicate that a <a>Buffer</a> is used for tracking
--   output.
data Out

-- | Recommended size for input buffer.
cstreamInSize :: CSize

-- | Recommended size for output buffer.
cstreamOutSize :: CSize

-- | Create a streaming compression context. This must be freed using
--   <a>freeCStream</a>, or if using a finalizer, with
--   <a>p_freeCStream</a>.
createCStream :: IO (Ptr CStream)

-- | Free a <a>CStream</a> value.
freeCStream :: Ptr CStream -> IO ()

-- | Free a <a>CStream</a> value. For use by a finalizer.
p_freeCStream :: FunPtr (Ptr CStream -> IO ())

-- | Begin a new compression operation.
initCStream :: Ptr CStream -> CInt -> IO CSize

-- | Consume part or all of an input.
compressStream :: Ptr CStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO CSize

-- | End a compression stream. This performs a flush and writes a frame
--   epilogue.
endStream :: Ptr CStream -> Ptr (Buffer Out) -> IO CSize

-- | Recommended size for input buffer.
dstreamInSize :: CSize

-- | Recommended size for output buffer.
dstreamOutSize :: CSize

-- | Create a streaming decompression context. This must be freed using
--   <a>freeDStream</a>, or if using a finalizer, with
--   <a>p_freeDStream</a>.
createDStream :: IO (Ptr DStream)

-- | Begin a new streaming decompression operation.
initDStream :: Ptr DStream -> IO CSize

-- | Consume part or all of an input.
decompressStream :: Ptr DStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO CSize

-- | Free a <a>CStream</a> value.
freeDStream :: Ptr DStream -> IO ()

-- | Free a <a>CStream</a> value. For use by a finalizer.
p_freeDStream :: FunPtr (Ptr DStream -> IO ())

-- | Train a dictionary from a collection of samples. Returns the number
--   size of the resulting dictionary.
trainFromBuffer :: Ptr dict -> CSize -> Ptr samples -> Ptr CSize -> CUInt -> IO CSize

-- | Return the identifier for the given dictionary, or zero if not a valid
--   dictionary.
getDictID :: Ptr dict -> CSize -> IO CUInt

-- | Compress bytes from source buffer into destination buffer, using a
--   prebuilt dictionary. The destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
compressUsingDict :: Ptr CCtx -> Ptr dst -> CSize -> Ptr src -> CSize -> Ptr dict -> CSize -> CInt -> IO CSize

-- | Decompress a buffer, using a prebuilt dictionary. The destination
--   buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
decompressUsingDict :: Ptr DCtx -> Ptr dst -> CSize -> Ptr src -> CSize -> Ptr dict -> CSize -> IO CSize

-- | An opaque pre-digested compression dictionary structure.
data CDict

-- | Allocate a pre-digested dictionary.
createCDict :: Ptr dict -> CSize -> CInt -> IO (Ptr CDict)

-- | Free a pre-digested dictionary.
freeCDict :: Ptr CDict -> IO ()

-- | Free a pre-digested dictionary.
p_freeCDict :: FunPtr (Ptr CDict -> IO ())

-- | Compress bytes from source buffer into destination buffer, using a
--   pre-built, pre-digested dictionary. The destination buffer must be
--   already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
compressUsingCDict :: Ptr CCtx -> Ptr dst -> CSize -> Ptr src -> CSize -> Ptr CDict -> IO CSize

-- | An opaque pre-digested decompression dictionary structure.
data DDict

-- | Allocate a pre-digested dictionary.
createDDict :: Ptr dict -> CSize -> IO (Ptr DDict)

-- | Free a pre-digested dictionary.
freeDDict :: Ptr DDict -> IO ()

-- | Free a pre-digested dictionary.
p_freeDDict :: FunPtr (Ptr DDict -> IO ())

-- | Decompress a buffer, using a pre-built, pre-digested dictionary. The
--   destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error code if it fails (which can be tested using <a>isError</a>).
decompressUsingDDict :: Ptr DCtx -> Ptr dst -> CSize -> Ptr src -> CSize -> Ptr DDict -> IO CSize

-- | Returns the maximum compression level supported by the library.
c_maxCLevel :: CInt


-- | Mid-level bindings to the native zstd compression library. These
--   bindings provide a little more safety and ease of use than the
--   lowest-level FFI bindings. Unless you have highly specialized needs,
--   you should use the streaming or other higher-level APIs instead.
module Codec.Compression.Zstd.Base

-- | Compress bytes from source buffer into destination buffer. The
--   destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
compress :: Ptr dst -> Int -> Ptr src -> Int -> Int -> IO (Either String Int)

-- | The maximum compression level supported by the library.
maxCLevel :: Int

-- | Decompress a buffer. The destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
decompress :: Ptr dst -> Int -> Ptr src -> Int -> IO (Either String Int)

-- | Returns the decompressed size of a compressed payload if known.
--   
--   To discover precisely why a result is not known, follow up with
--   <a>getFrameParams</a>.
getDecompressedSize :: Ptr src -> Int -> IO (Maybe Word64)

-- | An opaque compression context structure.
data CCtx

-- | Allocate a compression context, run an action that may reuse the
--   context as many times as it needs, then free the context.
withCCtx :: (Ptr CCtx -> IO a) -> IO a

-- | Compress bytes from source buffer into destination buffer. The
--   destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
compressCCtx :: Ptr CCtx -> Ptr dst -> Int -> Ptr src -> CSize -> Int -> IO (Either String Int)

-- | An opaque decompression context structure.
data DCtx

-- | Allocate a decompression context, run an action that may reuse the
--   context as many times as it needs, then free the context.
withDCtx :: (Ptr DCtx -> IO a) -> IO a

-- | Decompress a buffer. The destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
decompressDCtx :: Ptr DCtx -> Ptr dst -> Int -> Ptr src -> Int -> IO (Either String Int)

-- | A context for streaming compression.
data CStream

-- | A context for streaming decompression.
data DStream

-- | A streaming buffer type. The type parameter statically indicates
--   whether the buffer is used to track an input or output buffer.
data Buffer io
Buffer :: {-# UNPACK #-} !Ptr a -> {-# UNPACK #-} !CSize -> {-# UNPACK #-} !CSize -> Buffer io

-- | Pointer to the start of the buffer. This can be set once by the
--   caller, and read by the streaming function.
[bufPtr] :: Buffer io -> {-# UNPACK #-} !Ptr a

-- | Size of the buffer (in bytes). This can be set once by the caller, and
--   is read by the streaming function.
[bufSize] :: Buffer io -> {-# UNPACK #-} !CSize

-- | Current offset into the buffer (in bytes). This must be initially set
--   to zero by the caller, and is updated by the streaming function.
[bufPos] :: Buffer io -> {-# UNPACK #-} !CSize

-- | A tag type to indicate that a <a>Buffer</a> is used for tracking
--   input.
data In

-- | A tag type to indicate that a <a>Buffer</a> is used for tracking
--   output.
data Out

-- | Recommended size for input buffer.
cstreamInSize :: Int

-- | Recommended size for output buffer.
cstreamOutSize :: Int

-- | Create a <a>CStream</a> value. After use, this will eventually be
--   freed via a finalizer.
createCStream :: IO CStream

-- | Begin a new streaming compression operation.
initCStream :: CStream -> Int -> IO (Either String ())

-- | Consume part or all of an input.
compressStream :: CStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO (Either String Int)

-- | End a compression stream. This performs a flush and writes a frame
--   epilogue.
endStream :: CStream -> Ptr (Buffer Out) -> IO (Either String Int)

-- | Recommended size for input buffer.
dstreamInSize :: Int

-- | Recommended size for output buffer.
dstreamOutSize :: Int

-- | Create a streaming decompression context. After use, this will
--   eventually be freed via a finalizer.
createDStream :: IO DStream

-- | Begin a new streaming decompression operation.
initDStream :: DStream -> IO (Either String ())

-- | Consume part or all of an input.
decompressStream :: DStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO (Either String Int)

-- | Train a dictionary from a collection of samples. Returns the number
--   size of the resulting dictionary.
trainFromBuffer :: Ptr dict -> Int -> Ptr samples -> Ptr Int -> Int -> IO (Either String Int)

-- | Return the identifier for the given dictionary, or <a>Nothing</a> if
--   not a valid dictionary.
getDictID :: Ptr dict -> Int -> IO (Maybe Word)

-- | Compress bytes from source buffer into destination buffer. The
--   destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
compressUsingDict :: Ptr CCtx -> Ptr dst -> Int -> Ptr src -> Int -> Ptr dict -> Int -> Int -> IO (Either String Int)

-- | Decompress a buffer. The destination buffer must be already allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
decompressUsingDict :: Ptr DCtx -> Ptr dst -> Int -> Ptr src -> Int -> Ptr dict -> Int -> IO (Either String Int)

-- | A pre-digested compression dictionary.
data CDict

-- | Create a pre-digested compression dictionary. After use, this will
--   eventually be freed via a finalizer.
createCDict :: Ptr dict -> Int -> Int -> IO CDict

-- | Compress bytes from source buffer into destination buffer, using a
--   pre-digested dictionary. The destination buffer must be already
--   allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
compressUsingCDict :: Ptr CCtx -> Ptr dst -> Int -> Ptr src -> Int -> CDict -> IO (Either String Int)

-- | A pre-digested decompression dictionary.
data DDict

-- | Create a pre-digested decompression dictionary. After use, this will
--   eventually be freed via a finalizer.
createDDict :: Ptr dict -> Int -> IO DDict

-- | Decompress bytes from source buffer into destination buffer, using a
--   pre-digested dictionary. The destination buffer must be already
--   allocated.
--   
--   Returns the number of bytes written into destination buffer, or an
--   error description if it fails.
decompressUsingDDict :: Ptr DCtx -> Ptr dst -> Int -> Ptr src -> Int -> DDict -> IO (Either String Int)


-- | Streaming compression and decompression support for zstd.
module Codec.Compression.Zstd.Streaming

-- | The result of a streaming compression or decompression step.
data Result

-- | A single frame of transformed data, and an action that when executed
--   will yield the next step in the streaming operation. The action is
--   ephemeral; you should discard it as soon as you use it.
Produce :: ByteString -> IO Result -> Result

-- | Provide the function with more input for the streaming operation to
--   continue. This function is ephemeral. You should call it exactly once,
--   and discard it immediately after you call it.
--   
--   To signal the end of a stream of data, supply an <a>empty</a> input.
Consume :: (ByteString -> IO Result) -> Result

-- | An error has occurred. If an error occurs, the streaming operation
--   cannot continue.
Error :: String -> String -> Result

-- | The streaming operation has ended. This payload may be empty. If it is
--   not, it must be written out.
--   
--   A non-empty payload consists of a frame epilogue, possibly preceded by
--   any data left over from the final streaming step.
Done :: ByteString -> Result

-- | Begin a streaming compression operation.
--   
--   The initial result will be either an <a>Error</a> or a <a>Consume</a>.
compress :: Int -> IO Result

-- | Begin a streaming decompression operation.
--   
--   The initial result will be either an <a>Error</a> or a <a>Consume</a>.
decompress :: IO Result

-- | The maximum compression level supported by the library.
maxCLevel :: Int
instance GHC.Show.Show Codec.Compression.Zstd.Streaming.Result


-- | Lazy compression and decompression support for zstd. Under the hood,
--   these are implemented using the streaming APIs.
module Codec.Compression.Zstd.Lazy

-- | Compress a payload. The input will be consumed lazily, and the
--   compressed result generated lazily.
--   
--   <i>Note:</i> if any error occurs, compression will fail part-way
--   through with a call to <a>error</a>.
compress :: Int -> ByteString -> ByteString

-- | Decompress a payload. The input will be consumed lazily, and the
--   decompressed result generated lazily.
--   
--   <i>Note:</i> if any error occurs, decompression will fail part-way
--   through with a call to <a>error</a>.
decompress :: ByteString -> ByteString

-- | The maximum compression level supported by the library.
maxCLevel :: Int


-- | Types supporting zstd compression and decompression.
module Codec.Compression.Zstd.Types

-- | The result of a decompression operation.
data Decompress

-- | Either the compressed frame was empty, or it was compressed in
--   streaming mode and so its size is not known.
Skip :: Decompress

-- | An error occurred.
Error :: String -> Decompress

-- | The payload was successfully decompressed.
Decompress :: ByteString -> Decompress

-- | Compression dictionary.
newtype Dict
Dict :: ByteString -> Dict
[fromDict] :: Dict -> ByteString

-- | Smart constructor.
mkDict :: ByteString -> Dict
instance GHC.Classes.Ord Codec.Compression.Zstd.Types.Dict
instance GHC.Classes.Eq Codec.Compression.Zstd.Types.Dict
instance GHC.Show.Show Codec.Compression.Zstd.Types.Decompress
instance GHC.Read.Read Codec.Compression.Zstd.Types.Decompress
instance GHC.Classes.Eq Codec.Compression.Zstd.Types.Decompress
instance GHC.Show.Show Codec.Compression.Zstd.Types.Dict
instance GHC.Read.Read Codec.Compression.Zstd.Types.Dict
instance Control.DeepSeq.NFData Codec.Compression.Zstd.Types.Dict


-- | These functions allow for pre-allocation and reuse of relatively
--   expensive data structures, such as compression and decompression
--   contexts and dictionaries.
--   
--   If your application mostly deals with small payloads and is
--   particularly sensitive to latency or throughput, using these
--   pre-allocated structures may make a noticeable difference to
--   performance.
module Codec.Compression.Zstd.Efficient

-- | The result of a decompression operation.
data Decompress

-- | Either the compressed frame was empty, or it was compressed in
--   streaming mode and so its size is not known.
Skip :: Decompress

-- | An error occurred.
Error :: String -> Decompress

-- | The payload was successfully decompressed.
Decompress :: ByteString -> Decompress

-- | Return the decompressed size of a compressed payload, as stored in the
--   payload's header.
--   
--   The returned value will be <a>Nothing</a> if it is either not known
--   (probably because the payload was compressed using a streaming API),
--   empty, or too large to fit in an <a>Int</a>.
--   
--   <i>Note:</i> this value should not be trusted, as it can be controlled
--   by an attacker.
decompressedSize :: ByteString -> Maybe Int

-- | The maximum compression level supported by the library.
maxCLevel :: Int

-- | Compression context.
data CCtx

-- | Allocate a compression context, run an action that may reuse the
--   context as many times as it needs, then free the context.
withCCtx :: (CCtx -> IO a) -> IO a

-- | Compress the given data as a single zstd compressed frame.
compressCCtx :: CCtx -> Int -> ByteString -> IO ByteString

-- | Decompression context.
data DCtx

-- | Allocate a decompression context, run an action that may reuse the
--   context as many times as it needs, then free the context.
withDCtx :: (DCtx -> IO a) -> IO a

-- | Decompress a single-frame payload of known size. Typically this will
--   be a payload that was compressed with <tt>compress</tt>.
--   
--   <i>Note:</i> This function is not capable of decompressing a payload
--   generated by the streaming or lazy compression APIs.
decompressDCtx :: DCtx -> ByteString -> IO Decompress

-- | Compression dictionary.
data Dict

-- | Smart constructor.
mkDict :: ByteString -> Dict
fromDict :: Dict -> ByteString

-- | Create and train a compression dictionary from a collection of
--   samples.
--   
--   To create a well-trained dictionary, here are some useful guidelines
--   to keep in mind:
--   
--   <ul>
--   <li>A reasonable dictionary size is in the region of 100 KB. (Trying
--   to specify a dictionary size of less than a few hundred bytes will
--   probably fail.)</li>
--   <li>To train the dictionary well, it is best to supply a few thousand
--   training samples.</li>
--   <li>The combined size of all training samples should be 100 or more
--   times larger than the size of the dictionary.</li>
--   </ul>
trainFromSamples :: Int -> [ByteString] -> Either String Dict

-- | Return the identifier for the given dictionary, or <a>Nothing</a> if
--   not a valid dictionary.
getDictID :: Dict -> Maybe Word

-- | Compress the given data as a single zstd compressed frame, using a
--   prebuilt dictionary.
compressUsingDict :: Dict -> Int -> ByteString -> ByteString

-- | Decompress a single-frame payload of known size, using a prebuilt
--   dictionary. Typically this will be a payload that was compressed with
--   <a>compressUsingDict</a>.
--   
--   <i>Note:</i> This function is not capable of decompressing a payload
--   generated by the streaming or lazy compression APIs.
decompressUsingDict :: Dict -> ByteString -> Decompress

-- | A pre-digested compression dictionary.
data CDict

-- | Create a pre-digested compression dictionary.
createCDict :: Int -> Dict -> CDict

-- | Compress the given data as a single zstd compressed frame, using a
--   pre-built, pre-digested dictionary.
compressUsingCDict :: CCtx -> CDict -> ByteString -> IO ByteString

-- | A pre-digested decompression dictionary.
data DDict

-- | Create a pre-digested compression dictionary.
createDDict :: Dict -> DDict

-- | Decompress a single-frame payload of known size, using a pre-built,
--   pre-digested dictionary. Typically this will be a payload that was
--   compressed with <a>compressUsingCDict</a>.
--   
--   <i>Note:</i> This function is not capable of decompressing a payload
--   generated by the streaming or lazy compression APIs.
decompressUsingDDict :: DCtx -> DDict -> ByteString -> IO Decompress


-- | A fast lossless compression algorithm, targeting real-time compression
--   scenarios at zlib-level and better compression ratios.
module Codec.Compression.Zstd

-- | Compress the given data as a single zstd compressed frame.
compress :: Int -> ByteString -> ByteString

-- | The result of a decompression operation.
data Decompress

-- | Either the compressed frame was empty, or it was compressed in
--   streaming mode and so its size is not known.
Skip :: Decompress

-- | An error occurred.
Error :: String -> Decompress

-- | The payload was successfully decompressed.
Decompress :: ByteString -> Decompress

-- | Return the decompressed size of a compressed payload, as stored in the
--   payload's header.
--   
--   The returned value will be <a>Nothing</a> if it is either not known
--   (probably because the payload was compressed using a streaming API),
--   empty, or too large to fit in an <a>Int</a>.
--   
--   <i>Note:</i> this value should not be trusted, as it can be controlled
--   by an attacker.
decompressedSize :: ByteString -> Maybe Int

-- | Decompress a single-frame payload of known size. Typically this will
--   be a payload that was compressed with <a>compress</a>.
--   
--   <i>Note:</i> This function is not capable of decompressing a payload
--   generated by the streaming or lazy compression APIs.
decompress :: ByteString -> Decompress

-- | The maximum compression level supported by the library.
maxCLevel :: Int

-- | Compression dictionary.
data Dict

-- | Smart constructor.
mkDict :: ByteString -> Dict
fromDict :: Dict -> ByteString

-- | Create and train a compression dictionary from a collection of
--   samples.
--   
--   To create a well-trained dictionary, here are some useful guidelines
--   to keep in mind:
--   
--   <ul>
--   <li>A reasonable dictionary size is in the region of 100 KB. (Trying
--   to specify a dictionary size of less than a few hundred bytes will
--   probably fail.)</li>
--   <li>To train the dictionary well, it is best to supply a few thousand
--   training samples.</li>
--   <li>The combined size of all training samples should be 100 or more
--   times larger than the size of the dictionary.</li>
--   </ul>
trainFromSamples :: Int -> [ByteString] -> Either String Dict

-- | Return the identifier for the given dictionary, or <a>Nothing</a> if
--   not a valid dictionary.
getDictID :: Dict -> Maybe Word

-- | Compress the given data as a single zstd compressed frame, using a
--   prebuilt dictionary.
compressUsingDict :: Dict -> Int -> ByteString -> ByteString

-- | Decompress a single-frame payload of known size, using a prebuilt
--   dictionary. Typically this will be a payload that was compressed with
--   <a>compressUsingDict</a>.
--   
--   <i>Note:</i> This function is not capable of decompressing a payload
--   generated by the streaming or lazy compression APIs.
decompressUsingDict :: Dict -> ByteString -> Decompress