-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Bindings to Google's Snappy: A fast compression library -- -- Snappy is a fast (de)compression library. It is written in C++, -- but a basic set of C bindings is also provided. Although the C -- bindings only support the "raw" Snappy format, this package provides -- support for the Snappy "frame" format on top of the raw C API, -- enabling extremely fast (de)compression of lazy (streamed) data. @package snappy-c @version 0.1.1 -- | Raw format Snappy compression/decompression. -- -- 
--   import Codec.Compression.SnappyC.Raw qualified as Snappy
--
module Codec.Compression.SnappyC.Raw -- | Compress the input using Snappy. -- -- The result is in Snappy raw format, not the framing format. compress :: ByteString -> ByteString -- | Decompress the input using Snappy. -- -- Returns Nothing if the input is not in Snappy raw format or -- otherwise ill-formed. decompress :: ByteString -> Maybe ByteString -- | 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
--
module Codec.Compression.SnappyC.Framed -- | Compress the input using Snappy. -- -- The output stream is in Snappy frame format. compress :: ByteString -> ByteString -- | Determines how much data is put in each Snappy frame and whether it is -- compressed. data EncodeParams EncodeParams :: !FrameSize -> !Threshold -> EncodeParams -- | Exact amount of uncompressed data included in a single frame. [frameSize] :: EncodeParams -> !FrameSize -- | Compression threshold. [threshold] :: EncodeParams -> !Threshold -- | Number of bytes of uncompressed data. data FrameSize -- | Compression threshold, with explicit AlwaysCompress and -- NeverCompress settings. data Threshold -- | Compress everything AlwaysCompress :: Threshold -- | Compress nothing NeverCompress :: Threshold -- | 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. Ratio :: !Double -> Threshold -- | Compress the input using Snappy with the given -- EncodeParams. -- -- The output stream is in Snappy frame format. compressWithParams :: EncodeParams -> ByteString -> ByteString -- | The default frame size is 65536 bytes, which is the maximum allowed by -- the Snappy framing format description. defaultFrameSize :: FrameSize -- | Create a FrameSize. -- -- Must be within the inclusive range [ 1 .. 65536 ]. customFrameSize :: Int -> FrameSize -- | Unwrap a FrameSize unFrameSize :: FrameSize -> Int -- | Possible failure modes for decompression. data DecodeFailure DecompressionError :: ByteString -> DecodeFailure ReservedUnskippableFrameId :: Word8 -> DecodeFailure BadStreamId :: ByteString -> DecodeFailure BadChecksum :: ByteString -> Checksum -> Checksum -> DecodeFailure NotDone :: DecodeFailure -- | 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 :: HasCallStack => ByteString -> ByteString -- | 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. -- | Deprecated: Consider using decompress or decompressStep' -- instead decompress' :: ByteString -> Either DecodeFailure ByteString -- | Decode parameters data DecodeParams DecodeParams :: !Bool -> DecodeParams -- | 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. [verifyChecksum] :: DecodeParams -> !Bool -- | 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 :: HasCallStack => DecodeParams -> ByteString -> ByteString -- | 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. -- | Deprecated: Consider using decompressWithParams or decompressStep' -- instead decompressWithParams' :: DecodeParams -> ByteString -> Either DecodeFailure ByteString -- | Buffers uncompressed data for compression. data Encoder -- | 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. initializeEncoder :: (ByteString, Encoder) -- | 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. -- -- finalizeEncoder :: EncodeParams -> Encoder -> [ByteString] -- | Append the data to the Encoder buffer and do as much -- compression as possible. -- -- Postconditions: -- -- compressStep :: EncodeParams -> Encoder -> ByteString -> ([ByteString], Encoder) -- | Buffers compressed data for decompression and holds some useful -- decompression state. data Decoder -- | The empty Decoder, in an initial state. initializeDecoder :: Decoder -- | Verify that the Decoder is complete. -- -- If the Decoder's buffer still has data in it, NotDone is -- returned. finalizeDecoder :: Decoder -> Either DecodeFailure () -- | Append the data to the Decoder buffer and do as much -- decompression as possible. -- -- Throws an exception if any DecodeFailure occurs. decompressStep :: HasCallStack => DecodeParams -> Decoder -> ByteString -> ([ByteString], Decoder) -- | 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. decompressStep' :: DecodeParams -> Decoder -> ByteString -> Either DecodeFailure ([ByteString], Decoder)