packer-0.1.1: Fast byte serializer and unserializer

Portabilityunknown
Stabilityexperimental
MaintainerVincent Hanquez <vincent@snarc.org>
Safe HaskellNone

Data.Packer

Contents

Description

Simple packing module.

This is a tradeoff between a more pure / builder (binary, cereal, builder) and direct access to Storable or pointer manipulation

Synopsis

Types

data OutOfBoundPacking Source

Exception when trying to put bytes out of the memory bounds.

Constructors

OutOfBoundPacking Int Int 

data Hole a Source

A Hole represent something that need to be filled later, for example a CRC, a prefixed size, etc.

They need to be filled before the end of the package, otherwise an exception will be raised.

Main methods

runUnpacking :: Unpacking a -> ByteString -> aSource

Unpack a bytestring using a monadic unpack action.

tryUnpacking :: Unpacking a -> ByteString -> Either SomeException aSource

Similar to runUnpacking but returns an Either type with an exception type in case of failure.

runPacking :: Int -> Packing () -> ByteStringSource

Run packing with a buffer created internally with a monadic action and return the bytestring

Unpacking functions

unpackSkip :: Int -> Unpacking ()Source

Skip bytes

unpackSetPosition :: Int -> Unpacking ()Source

Set the new position from the beginning in the memory block. This is useful to skip bytes or when using absolute offsets from a header or some such.

unpackGetPosition :: Unpacking IntSource

Get the position in the memory block.

getWord16 :: Unpacking Word16Source

Get a Word16 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when unserializing format.

getWord16LE :: Unpacking Word16Source

Get a Word16 serialized in little endian.

getWord16BE :: Unpacking Word16Source

Get a Word16 serialized in big endian.

getWord32 :: Unpacking Word32Source

Get a Word32 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when unserializing format.

getWord32LE :: Unpacking Word32Source

Get a Word32 serialized in little endian.

getWord32BE :: Unpacking Word32Source

Get a Word32 serialized in big endian.

getWord64 :: Unpacking Word64Source

Get a Word64 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when unserializing format.

getWord64LE :: Unpacking Word64Source

Get a Word64 serialized in little endian.

getWord64BE :: Unpacking Word64Source

Get a Word64 serialized in big endian.

getBytes :: Int -> Unpacking ByteStringSource

Get a number of bytes in bytestring format.

The original block of memory is expected to live for the life of this bytestring, and this is done so by holding the original ForeignPtr.

getBytesCopy :: Int -> Unpacking ByteStringSource

Similar to getBytes but copy the bytes to a new bytestring without making reference to the original memory after the copy. this allow the original block of memory to go away.

getBytesWhile :: (Word8 -> Bool) -> Unpacking (Maybe ByteString)Source

Get a number of bytes until in bytestring format.

this could be made more efficient

getRemaining :: Unpacking ByteStringSource

Get the remaining bytes.

getRemainingCopy :: Unpacking ByteStringSource

Get the remaining bytes but copy the bytestring and drop any reference from the original function.

getStorable :: Storable a => Unpacking aSource

Get an arbitrary type with the Storable class constraint.

Packing functions

packGetPosition :: Packing IntSource

Get the position in the memory block.

putWord8 :: Word8 -> Packing ()Source

Put a Word8

putWord16 :: Word16 -> Packing ()Source

Put a Word16 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when serializing format.

putWord16LE :: Word16 -> Packing ()Source

Put a Word16 serialized in little endian.

putWord16BE :: Word16 -> Packing ()Source

Put a Word16 serialized in big endian.

putWord32 :: Word32 -> Packing ()Source

Put a Word32 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when serializing format.

putWord32LE :: Word32 -> Packing ()Source

Put a Word32 serialized in little endian.

putWord32BE :: Word32 -> Packing ()Source

Put a Word32 serialized in big endian.

putHoleWord32 :: Packing (Hole Word32)Source

Put a Word32 Hole in host endian

putHoleWord32LE :: Packing (Hole Word32)Source

Put a Word32 Hole in little endian

putHoleWord32BE :: Packing (Hole Word32)Source

Put a Word32 Hole in big endian

putWord64 :: Word64 -> Packing ()Source

Put a Word64 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when serializing format.

putWord64LE :: Word64 -> Packing ()Source

Put a Word64 serialized in little endian.

putWord64BE :: Word64 -> Packing ()Source

Put a Word64 serialized in big endian.

putHoleWord64 :: Packing (Hole Word64)Source

Put a Word64 Hole in host endian

putHoleWord64LE :: Packing (Hole Word64)Source

Put a Word64 Hole in little endian

putHoleWord64BE :: Packing (Hole Word64)Source

Put a Word64 Hole in big endian

putBytes :: ByteString -> Packing ()Source

Put a Bytestring.

putStorable :: Storable a => a -> Packing ()Source

Put an arbitrary type with the Storable class constraint.

fillHole :: Hole a -> a -> Packing ()Source

Fill a hole with a value

TODO: user can use one hole many times leading to wrong counting.