Codec.Compression.Zstd.Base

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.

One-shot functions

compress

Arguments

:: Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> Int

Size of source buffer.

-> Int

Compression level.

-> IO (Either String Int)

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.

maxCLevel :: Int

The maximum compression level supported by the library.

decompress

Arguments

:: Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> Int

Size of compressed input. This must be exact, so for example supplying the size of a buffer that is larger than the compressed input will cause a failure.

-> 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.

getDecompressedSize :: Ptr src -> Int -> IO (Maybe Word64)

Returns the decompressed size of a compressed payload if known.

To discover precisely why a result is not known, follow up with getFrameParams.

Cheaper operations using contexts

Compression

data CCtx

An opaque compression context structure.

withCCtx :: (Ptr CCtx -> IO a) -> IO a

Allocate a compression context, run an action that may reuse the context as many times as it needs, then free the context.

compressCCtx

Arguments

:: Ptr CCtx

Compression context.

-> Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> CSize

Size of source buffer.

-> Int

Compression level.

-> IO (Either String Int)

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.

Decompression

data DCtx

An opaque decompression context structure.

withDCtx :: (Ptr DCtx -> IO a) -> IO a

Allocate a decompression context, run an action that may reuse the context as many times as it needs, then free the context.

decompressDCtx

Arguments

:: Ptr DCtx

Decompression context.

-> Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> Int

Size of compressed input. This must be exact, so for example supplying the size of a buffer that is larger than the compressed input will cause a failure.

-> 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.

Streaming operations

Streaming types

data CStream

A context for streaming compression.

data DStream

A context for streaming decompression.

data Buffer io

A streaming buffer type. The type parameter statically indicates whether the buffer is used to track an input or output buffer.

Constructors

Buffer

Fields

• bufPtr :: !(Ptr a)

  Pointer to the start of the buffer. This can be set once by the caller, and read by the streaming function.

• bufSize :: !CSize

  Size of the buffer (in bytes). This can be set once by the caller, and is read by the streaming function.

• bufPos :: !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.

Instances

Storable (Buffer io)

Defined in Codec.Compression.Zstd.FFI.Types

Methods

sizeOf :: Buffer io -> Int

alignment :: Buffer io -> Int

peekElemOff :: Ptr (Buffer io) -> Int -> IO (Buffer io)

pokeElemOff :: Ptr (Buffer io) -> Int -> Buffer io -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Buffer io)

pokeByteOff :: Ptr b -> Int -> Buffer io -> IO ()

peek :: Ptr (Buffer io) -> IO (Buffer io)

poke :: Ptr (Buffer io) -> Buffer io -> IO ()

data In

A tag type to indicate that a Buffer is used for tracking input.

data Out

A tag type to indicate that a Buffer is used for tracking output.

Streaming compression

cstreamInSize :: Int

Recommended size for input buffer.

cstreamOutSize :: Int

Recommended size for output buffer.

createCStream :: IO CStream

Create a CStream value. After use, this will eventually be freed via a finalizer.

initCStream

Arguments

:: CStream

-> Int

Compression level.

-> IO (Either String ())

Begin a new streaming compression operation.

compressStream :: CStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO (Either String Int)

Consume part or all of an input.

endStream :: CStream -> Ptr (Buffer Out) -> IO (Either String Int)

End a compression stream. This performs a flush and writes a frame epilogue.

Streaming decompression

dstreamInSize :: Int

Recommended size for input buffer.

dstreamOutSize :: Int

Recommended size for output buffer.

createDStream :: IO DStream

Create a streaming decompression context. After use, this will eventually be freed via a finalizer.

initDStream :: DStream -> IO (Either String ())

Begin a new streaming decompression operation.

decompressStream :: DStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO (Either String Int)

Consume part or all of an input.

Dictionary compression

trainFromBuffer

Arguments

:: Ptr dict

Preallocated dictionary buffer.

-> Int

Capacity of dictionary buffer.

-> Ptr samples

Concatenated samples.

-> Ptr Int

Array of sizes of samples.

-> Int

Number of samples.

-> IO (Either String Int)

Train a dictionary from a collection of samples. Returns the number size of the resulting dictionary.

getDictID :: Ptr dict -> Int -> IO (Maybe Word)

Return the identifier for the given dictionary, or Nothing if not a valid dictionary.

compressUsingDict

Arguments

:: Ptr CCtx

-> Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> Int

Size of source buffer.

-> Ptr dict

Dictionary.

-> Int

Size of dictionary.

-> Int

Compression level.

-> IO (Either String Int)

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.

decompressUsingDict

Arguments

:: Ptr DCtx

-> Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> Int

Size of compressed input. This must be exact, so for example supplying the size of a buffer that is larger than the compressed input will cause a failure.

-> Ptr dict

Dictionary.

-> Int

Size of dictionary.

-> 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.

Pre-digested dictionaries

Compression

data CDict

A pre-digested compression dictionary.

createCDict

Arguments

:: Ptr dict

Dictionary.

-> Int

Size of dictionary.

-> Int

Compression level.

-> IO CDict

Create a pre-digested compression dictionary. After use, this will eventually be freed via a finalizer.

compressUsingCDict

Arguments

:: Ptr CCtx

Compression context.

-> Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> Int

Size of source buffer.

-> CDict

Dictionary.

-> IO (Either String Int)

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.

Decompression

data DDict

A pre-digested decompression dictionary.

createDDict

Arguments

:: Ptr dict

Dictionary.

-> Int

Size of dictionary.

-> IO DDict

Create a pre-digested decompression dictionary. After use, this will eventually be freed via a finalizer.

decompressUsingDDict

Arguments

:: Ptr DCtx

Compression context.

-> Ptr dst

Destination buffer.

-> Int

Capacity of destination buffer.

-> Ptr src

Source buffer.

-> Int

Size of source buffer.

-> DDict

Dictionary.

-> IO (Either String Int)

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.