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

Contents

Basic pure API
Dictionary-based compression
- Basic pure API

Description

A fast lossless compression algorithm, targeting real-time compression scenarios at zlib-level and better compression ratios.

Synopsis

compress :: Int -> ByteString -> ByteString
data Decompress
- = Skip
- | Error String
- | Decompress ByteString
decompressedSize :: ByteString -> Maybe Int
decompress :: ByteString -> Decompress
maxCLevel :: Int
data Dict
mkDict :: ByteString -> Dict
fromDict :: Dict -> ByteString
trainFromSamples :: Int -> [ByteString] -> Either String Dict
getDictID :: Dict -> Maybe Word
compressUsingDict :: Dict -> Int -> ByteString -> ByteString
decompressUsingDict :: Dict -> ByteString -> Decompress

Basic pure API

compress Source #

Arguments

:: Int	Compression level. Must be >= 1 and <= `maxCLevel`.
-> ByteString	Payload to compress.
-> ByteString

Compress the given data as a single zstd compressed frame.

data Decompress Source #

The result of a decompression operation.

Constructors

Skip	Either the compressed frame was empty, or it was compressed in streaming mode and so its size is not known.
Error String	An error occurred.
Decompress ByteString	The payload was successfully decompressed.

Instances

Eq Decompress Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods (==) :: Decompress -> Decompress -> Bool # (/=) :: Decompress -> Decompress -> Bool #
Read Decompress Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods readsPrec :: Int -> ReadS Decompress # readList :: ReadS [Decompress] # readPrec :: ReadPrec Decompress # readListPrec :: ReadPrec [Decompress] #
Show Decompress Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods showsPrec :: Int -> Decompress -> ShowS # show :: Decompress -> String # showList :: [Decompress] -> ShowS #

decompressedSize :: ByteString -> Maybe Int Source #

Return the decompressed size of a compressed payload, as stored in the payload's header.

The returned value will be Nothing if it is either not known (probably because the payload was compressed using a streaming API), empty, or too large to fit in an Int.

Note: this value should not be trusted, as it can be controlled by an attacker.

decompress :: ByteString -> Decompress Source #

Decompress a single-frame payload of known size. Typically this will be a payload that was compressed with compress.

Note: This function is not capable of decompressing a payload generated by the streaming or lazy compression APIs.

maxCLevel :: Int Source #

The maximum compression level supported by the library.

Dictionary-based compression

data Dict Source #

Compression dictionary.

Instances

Eq Dict Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods (==) :: Dict -> Dict -> Bool # (/=) :: Dict -> Dict -> Bool #
Ord Dict Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods compare :: Dict -> Dict -> Ordering # (<) :: Dict -> Dict -> Bool # (<=) :: Dict -> Dict -> Bool # (>) :: Dict -> Dict -> Bool # (>=) :: Dict -> Dict -> Bool # max :: Dict -> Dict -> Dict # min :: Dict -> Dict -> Dict #
Read Dict Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods readsPrec :: Int -> ReadS Dict # readList :: ReadS [Dict] # readPrec :: ReadPrec Dict # readListPrec :: ReadPrec [Dict] #
Show Dict Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods showsPrec :: Int -> Dict -> ShowS # show :: Dict -> String # showList :: [Dict] -> ShowS #
NFData Dict Source #
Instance details Defined in Codec.Compression.Zstd.Types Methods rnf :: Dict -> () #

mkDict :: ByteString -> Dict Source #

Smart constructor.

fromDict :: Dict -> ByteString Source #

trainFromSamples Source #

Arguments

:: Int	Maximum size of the compression dictionary to create. The actual dictionary returned may be smaller.
-> [ByteString]	Samples to train with.
-> Either String Dict

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:

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.)
To train the dictionary well, it is best to supply a few thousand training samples.
The combined size of all training samples should be 100 or more times larger than the size of the dictionary.

getDictID :: Dict -> Maybe Word Source #

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

Basic pure API

compressUsingDict Source #

Arguments

:: Dict	Compression dictionary.
-> Int	Compression level. Must be >= 1 and <= `maxCLevel`.
-> ByteString	Payload to compress.
-> ByteString

Compress the given data as a single zstd compressed frame, using a prebuilt dictionary.

decompressUsingDict Source #

Arguments

:: Dict	Dictionary.
-> ByteString	Payload to decompress.
-> Decompress

Decompress a single-frame payload of known size, using a prebuilt dictionary. Typically this will be a payload that was compressed with compressUsingDict.

Note: This function is not capable of decompressing a payload generated by the streaming or lazy compression APIs.