Copyright	(c) 2024 Finley McIlwaine
License	BSD-3-Clause (see LICENSE)
Maintainer	Finley McIlwaine <finley@well-typed.com>
Safe Haskell	None
Language	Haskell2010

Codec.Compression.SnappyC.Framed

Contents

Compression
- Compression with custom parameters
Decompression
- Decompression with custom parameters
Low-level incremental API
- Compression
- Decompression

Description

Frame format Snappy compression/decompression. See the framing format description here: https://github.com/google/snappy/blob/main/framing_format.txt

Intended for qualified import:

import Codec.Compression.SnappyC.Framed qualified as Snappy

Synopsis

compress :: ByteString -> ByteString
data EncodeParams = EncodeParams {
- frameSize :: !FrameSize
- threshold :: !Threshold
}
data FrameSize
data Threshold
- = AlwaysCompress
- | NeverCompress
- | Ratio !Double
compressWithParams :: EncodeParams -> ByteString -> ByteString
defaultFrameSize :: FrameSize
customFrameSize :: Int -> FrameSize
unFrameSize :: FrameSize -> Int
data DecodeFailure
- = DecompressionError ByteString
- | ReservedUnskippableFrameId Word8
- | BadStreamId ByteString
- | BadChecksum ByteString Checksum Checksum
- | NotDone
decompress :: HasCallStack => ByteString -> ByteString
decompress' :: ByteString -> Either DecodeFailure ByteString
data DecodeParams = DecodeParams {
- verifyChecksum :: !Bool
}
decompressWithParams :: HasCallStack => DecodeParams -> ByteString -> ByteString
decompressWithParams' :: DecodeParams -> ByteString -> Either DecodeFailure ByteString
data Encoder
initializeEncoder :: (ByteString, Encoder)
finalizeEncoder :: EncodeParams -> Encoder -> [ByteString]
compressStep :: EncodeParams -> Encoder -> ByteString -> ([ByteString], Encoder)
data Decoder
initializeDecoder :: Decoder
finalizeDecoder :: Decoder -> Either DecodeFailure ()
decompressStep :: HasCallStack => DecodeParams -> Decoder -> ByteString -> ([ByteString], Decoder)
decompressStep' :: DecodeParams -> Decoder -> ByteString -> Either DecodeFailure ([ByteString], Decoder)

Compression

compress :: ByteString -> ByteString Source #

Compress the input using Snappy.

The output stream is in Snappy frame format.

Compression with custom parameters

data EncodeParams Source #

Determines how much data is put in each Snappy frame and whether it is compressed.

Constructors

EncodeParams
Fields frameSize :: !FrameSize Exact amount of uncompressed data included in a single frame. threshold :: !Threshold Compression threshold.

Instances

Instances details

Show EncodeParams Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods showsPrec :: Int -> EncodeParams -> ShowS # show :: EncodeParams -> String # showList :: [EncodeParams] -> ShowS #
Default EncodeParams Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods def :: EncodeParams #
Eq EncodeParams Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods (==) :: EncodeParams -> EncodeParams -> Bool # (/=) :: EncodeParams -> EncodeParams -> Bool #

data FrameSize Source #

Number of bytes of uncompressed data.

Instances

Instances details

Show FrameSize Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods showsPrec :: Int -> FrameSize -> ShowS # show :: FrameSize -> String # showList :: [FrameSize] -> ShowS #
Default FrameSize Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods def :: FrameSize #
Eq FrameSize Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods (==) :: FrameSize -> FrameSize -> Bool # (/=) :: FrameSize -> FrameSize -> Bool #

data Threshold Source #

Compression threshold, with explicit AlwaysCompress and NeverCompress settings.

Constructors

AlwaysCompress

Compress everything

NeverCompress

Compress nothing

Ratio !Double

Uncompressed size divided by compressed size.

Only produce compressed frames if the compression ratio for the data is equal to or above this threshold.

A higher threshold may result in less frames holding compressed data, and thus faster decompression/decoding.

According to Google, the typical highest compression ratio that Snappy achieves is about 4, so a Ratio of > 4.0 should be similar to NeverCompress, while a Ratio of < 7/8 should be similar to AlwaysCompress.

Instances

Instances details

Show Threshold Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods showsPrec :: Int -> Threshold -> ShowS # show :: Threshold -> String # showList :: [Threshold] -> ShowS #
Default Threshold Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods def :: Threshold #
Eq Threshold Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods (==) :: Threshold -> Threshold -> Bool # (/=) :: Threshold -> Threshold -> Bool #

compressWithParams :: EncodeParams -> ByteString -> ByteString Source #

Compress the input using Snappy with the given EncodeParams.

The output stream is in Snappy frame format.

defaultFrameSize :: FrameSize Source #

The default frame size is 65536 bytes, which is the maximum allowed by the Snappy framing format description.

customFrameSize :: Int -> FrameSize Source #

Create a FrameSize.

Must be within the inclusive range [ 1 .. 65536 ].

unFrameSize :: FrameSize -> Int Source #

Unwrap a FrameSize

Decompression

data DecodeFailure Source #

Possible failure modes for decompression.

Constructors

DecompressionError ByteString
ReservedUnskippableFrameId Word8
BadStreamId ByteString
BadChecksum
Fields ByteString Data Checksum Received Checksum Computed
NotDone

Instances

Instances details

Exception DecodeFailure Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods toException :: DecodeFailure -> SomeException # fromException :: SomeException -> Maybe DecodeFailure # displayException :: DecodeFailure -> String #
Show DecodeFailure Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods showsPrec :: Int -> DecodeFailure -> ShowS # show :: DecodeFailure -> String # showList :: [DecodeFailure] -> ShowS #

decompress :: HasCallStack => ByteString -> ByteString Source #

Decompress the input using Snappy.

The input stream is expected to be in the official Snappy frame format.

Note: The extra laziness of this function (compared to decompress') comes at the cost of potential exceptions during decompression.

decompress' :: ByteString -> Either DecodeFailure ByteString Source #

Deprecated: Consider using decompress or decompressStep' instead

Decompress the input using Snappy.

The input stream is expected to be in the official Snappy frame format. Evaluates to a DecodeFailure if the input stream is ill-formed.

WARNING: This function is not as lazy as you might hope. To determine whether the result is a DecodeFailure, it must load the entire source ByteString into memory during decompression. Use either decompressWithParams or the incremental decompressStep' instead. If you are truly okay with the extra memory overhead, you may ignore this warning.

Decompression with custom parameters

data DecodeParams Source #

Decode parameters

Constructors

DecodeParams

Fields

verifyChecksum :: !Bool
Verify the uncompressed data checksums during decompression
Defaults to False. Even if we don't verify the CRC, if the data is not Snappy compressed then decompression will likely still fail due to failing to decode the frame headers.
To enable this, use the incremental API (decompressStep). Note that checksum verification adds a significant overhead to decompression.

Instances

Instances details

Show DecodeParams Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods showsPrec :: Int -> DecodeParams -> ShowS # show :: DecodeParams -> String # showList :: [DecodeParams] -> ShowS #
Default DecodeParams Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods def :: DecodeParams #
Eq DecodeParams Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods (==) :: DecodeParams -> DecodeParams -> Bool # (/=) :: DecodeParams -> DecodeParams -> Bool #

decompressWithParams :: HasCallStack => DecodeParams -> ByteString -> ByteString Source #

Decompress the input using Snappy with the given DecodeParams.

The input stream is expected to be in the official Snappy frame format.

Note: The extra laziness of this function (compared to decompressWithParams') comes at the cost of potential exceptions during decompression.

decompressWithParams' :: DecodeParams -> ByteString -> Either DecodeFailure ByteString Source #

Deprecated: Consider using decompressWithParams or decompressStep' instead

Decompress the input using Snappy with the given DecodeParams.

The input stream is expected to be in the official Snappy frame format. Evaluates to a DecodeFailure if the input stream is ill-formed.

WARNING: This function is not as lazy as you might hope. To determine whether the result is a DecodeFailure, it must load the entire source ByteString into memory during decompression. Use either decompressWithParams or the incremental decompressStep' instead. If you are truly okay with the extra memory overhead, you may ignore this warning.

Low-level incremental API

Compression

data Encoder Source #

Buffers uncompressed data for compression.

Instances

Instances details

Show Encoder Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods showsPrec :: Int -> Encoder -> ShowS # show :: Encoder -> String # showList :: [Encoder] -> ShowS #

initializeEncoder :: (ByteString, Encoder) Source #

Initialize an Encoder with the given maximum number of bytes of uncompressed data to include in frames resulting from the Encoder. If the given number of bytes is not in the inclusive range [1 .. 65536], 65536 is used.

The ByteString holds the Snappy stream identifier frame that must be included at the start of every Snappy frame encoded stream.

finalizeEncoder :: EncodeParams -> Encoder -> [ByteString] Source #

Call to indicate no more input and flush the remaining data in the Encoder into a new frame.

If there is no more data in the Encoder, an empty list is returned.

Precondition: The buffer does not hold more data than the frameSize in the EncodeParams. Use the postcondition of encodeBuffered to ensure this.

compressStep :: EncodeParams -> Encoder -> ByteString -> ([ByteString], Encoder) Source #

Append the data to the Encoder buffer and do as much compression as possible.

Postconditions:

The resulting Encoder will not have more data in its buffer than the chunkSize in the EncodeParams.
Each encoded frame will hold exactly one chunkSize worth of uncompressed data.

Decompression

data Decoder Source #

Buffers compressed data for decompression and holds some useful decompression state.

Instances

Instances details

Show Decoder Source #
Instance details Defined in Codec.Compression.SnappyC.Internal.FrameFormat Methods showsPrec :: Int -> Decoder -> ShowS # show :: Decoder -> String # showList :: [Decoder] -> ShowS #

initializeDecoder :: Decoder Source #

The empty Decoder, in an initial state.

finalizeDecoder :: Decoder -> Either DecodeFailure () Source #

Verify that the Decoder is complete.

If the Decoder's buffer still has data in it, NotDone is returned.

decompressStep :: HasCallStack => DecodeParams -> Decoder -> ByteString -> ([ByteString], Decoder) Source #

Append the data to the Decoder buffer and do as much decompression as possible.

Throws an exception if any DecodeFailure occurs.

decompressStep' :: DecodeParams -> Decoder -> ByteString -> Either DecodeFailure ([ByteString], Decoder) Source #

Append the data to the Decoder buffer and do as much decompression as possible.

Note: This function is not as lazy as decompressStep, since it must completely decode the given chunk before providing a result.