zstd-0.1.3.0: Haskell bindings to the Zstandard compression algorithm

Copyright | (c) 2016-present Facebook Inc. All rights reserved.
License | BSD3
Maintainer | bryano@fb.com
Stability | experimental
Portability | GHC
Safe Haskell | None
Language | Haskell2010

Codec.Compression.Zstd.Base

Contents

- One-shot functions
  - Cheaper operations using contexts
    - Compression
    - Decompression
- Streaming operations
  - Streaming types
  - Streaming compression
  - Streaming decompression
- Dictionary compression
  - Pre-digested dictionaries
    - Compression
    - Decompression

Description

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.

Synopsis

- compress :: Ptr dst -> Int -> Ptr src -> Int -> Int -> IO (Either String Int)
- maxCLevel :: Int
- decompress :: Ptr dst -> Int -> Ptr src -> Int -> IO (Either String Int)
- getDecompressedSize :: Ptr src -> Int -> IO (Maybe Word64)
- data CCtx
- withCCtx :: (Ptr CCtx -> IO a) -> IO a
- compressCCtx :: Ptr CCtx -> Ptr dst -> Int -> Ptr src -> CSize -> Int -> IO (Either String Int)
- data DCtx
- withDCtx :: (Ptr DCtx -> IO a) -> IO a
- decompressDCtx :: Ptr DCtx -> Ptr dst -> Int -> Ptr src -> Int -> IO (Either String Int)
- data CStream
- data DStream
- data Buffer io = Buffer {
  - bufPtr :: !(Ptr a)
  - bufSize :: !CSize
  - bufPos :: !CSize
  }
- data In
- data Out
- cstreamInSize :: Int
- cstreamOutSize :: Int
- createCStream :: IO CStream
- initCStream :: CStream -> Int -> IO (Either String ())
- compressStream :: CStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO (Either String Int)
- endStream :: CStream -> Ptr (Buffer Out) -> IO (Either String Int)
- dstreamInSize :: Int
- dstreamOutSize :: Int
- createDStream :: IO DStream
- initDStream :: DStream -> IO (Either String ())
- decompressStream :: DStream -> Ptr (Buffer Out) -> Ptr (Buffer In) -> IO (Either String Int)
- trainFromBuffer :: Ptr dict -> Int -> Ptr samples -> Ptr Int -> Int -> IO (Either String Int)
- getDictID :: Ptr dict -> Int -> IO (Maybe Word)
- compressUsingDict :: Ptr CCtx -> Ptr dst -> Int -> Ptr src -> Int -> Ptr dict -> Int -> Int -> IO (Either String Int)
- decompressUsingDict :: Ptr DCtx -> Ptr dst -> Int -> Ptr src -> Int -> Ptr dict -> Int -> IO (Either String Int)
- data CDict
- createCDict :: Ptr dict -> Int -> Int -> IO CDict
- compressUsingCDict :: Ptr CCtx -> Ptr dst -> Int -> Ptr src -> Int -> CDict -> IO (Either String Int)
- data DDict
- createDDict :: Ptr dict -> Int -> IO DDict
- decompressUsingDDict :: Ptr DCtx -> Ptr dst -> Int -> Ptr src -> Int -> DDict -> IO (Either String Int)

# One-shot functions

compress Source #

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 Source #

The maximum compression level supported by the library.

decompress Source #

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) Source #

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 Source #

An opaque compression context structure.

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

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

compressCCtx Source #

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 Source #

An opaque decompression context structure.

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

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

decompressDCtx Source #

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 Source #

A context for streaming compression.

data DStream Source #

A context for streaming decompression.

data Buffer io Source #

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

Instances details

Storable (Buffer io) Source # |

Instance details

Defined in Codec.Compression.Zstd.FFI.Types

Methods

sizeOf :: Buffer io -> Int Source #

alignment :: Buffer io -> Int Source #

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

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

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

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

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

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

data In Source #

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

data Out Source #

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

## Streaming compression

cstreamInSize :: Int Source #

Recommended size for input buffer.

cstreamOutSize :: Int Source #

Recommended size for output buffer.

createCStream :: IO CStream Source #

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

initCStream Source #

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) Source #

Consume part or all of an input.

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

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

## Streaming decompression

dstreamInSize :: Int Source #

Recommended size for input buffer.

dstreamOutSize :: Int Source #

Recommended size for output buffer.

createDStream :: IO DStream Source #

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

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

Begin a new streaming decompression operation.

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

Consume part or all of an input.

# Dictionary compression

trainFromBuffer Source #

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) Source #

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

compressUsingDict Source #

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 Source #

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 Source #

A pre-digested compression dictionary.

createCDict Source #

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 Source #

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 Source #

A pre-digested decompression dictionary.

createDDict Source #

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 Source #

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.