Data.BinaryList.Serialize

Serialization methods for binary lists.

Simple interface

encode :: Binary a => BinList a -> ByteString

Encode a binary list using the Binary instance of its elements.

decode :: Binary a => ByteString -> Either String (BinList a)

Decode a binary list using the Binary instance of its elements. It returns a String in case of decoding failure.

Other methods

data Direction

Direction of encoding. If the direction is FromLeft, the binary list will be encoded from left to right. If the direction is FromRight, the binary list will be encoded in the opposite way. Choose a direction according to the part of the list you want to have access earlier. If you foresee reading only a part of the list, either at its beginning or end, an appropiate choice of direction will allow you to avoid decoding the full list.

Constructors

FromLeft

FromRight

Instances

Eq Direction

Encoding

data EncodedBinList

A binary list encoded, ready to be written in a file or be sent over a network. It can be directly translated to a ByteString using encodedToByteString, or restored using encodedFromByteString.

Constructors

EncodedBinList

Fields

encDirection :: Direction

Direction of encoding.

encLength :: Int

Length index (see lengthIndex) of the binary list.

encData :: ByteString

Encoded data.

encodeBinList :: (a -> Put) -> Direction -> BinList a -> EncodedBinList

Encode a binary list, using a custom serialization for its elements and an user-supplied direction.

Decoding

data DecodedBinList a

A binary list decoded, from where you can extract a binary list. If the decoding process fails in some point, you still will be able to retrieve the binary list of elements that were decoded successfully before the error.

Constructors

DecodedBinList

Fields

decDirection :: Direction

Direction of encoding.

decLength :: Int

Length index (see lengthIndex) of the binary list.

decData :: Decoded a

Decoded data.

data Decoded a

The result of decoding a binary list, which produces a list of binary lists of increasing size, ending in either a decoding error or a final binary list. When this is the result of decodeBinList, it contains sublists of order 1, 2, 4, 8, ... up to the order of the total list (unless an error has been encountered first). These sublists are either a section starting at the left, or a section starting at the right, depending on the Direction of encoding.

Constructors

PartialResult (BinList a) (Decoded a)

Partial binary list, and rest of decoded input.

FinalResult (BinList a) ByteString

Full binary list and remaining input.

DecodingError String ByteString

A decoding error, with an error message and the remaining input.

fromDecoded :: Decoded a -> Either String (BinList a)

Get the final result of a decoding process, unless it returned an error, in which case this error is returned as a String.

toDecoded :: BinList a -> Decoded a

Break a list down to sublists of order 1, 2, 4, 8, ..., 2^k. The result is stored in a Decoded value. Obviously, the output will not have a decoding error.

decodeBinList :: Get a -> EncodedBinList -> DecodedBinList a

Decode an encoded binary list. The result is given as a DecodedBinList value, which can then be queried to get partial results.

ByteString translations

encodedToByteString :: EncodedBinList -> ByteString

Translate an encoded binary list to a bytestring.

encodedFromByteString :: ByteString -> Either String EncodedBinList

Translate a bytestring to an encoded binary list, in case this is possible. Otherwise, it returns a string with a human-readable error.