packer-0.1.9: Fast byte serializer and unserializer

LicenseBSD-style
MaintainerVincent Hanquez <vincent@snarc.org>
Stabilityexperimental
Portabilityunknown
Safe HaskellNone
LanguageHaskell98

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 -> a Source

Unpack a bytestring using a monadic unpack action.

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

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

runPacking :: Int -> Packing a -> ByteString Source

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

runPackingRes :: Int -> Packing a -> (a, ByteString) Source

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 Int Source

Get the position in the memory block.

getWord16 :: Unpacking Word16 Source

Get a Word16 in the host endianess.

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

getWord16LE :: Unpacking Word16 Source

Get a Word16 serialized in little endian.

getWord16BE :: Unpacking Word16 Source

Get a Word16 serialized in big endian.

getWord32 :: Unpacking Word32 Source

Get a Word32 in the host endianess.

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

getWord32LE :: Unpacking Word32 Source

Get a Word32 serialized in little endian.

getWord32BE :: Unpacking Word32 Source

Get a Word32 serialized in big endian.

getWord64 :: Unpacking Word64 Source

Get a Word64 in the host endianess.

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

getWord64LE :: Unpacking Word64 Source

Get a Word64 serialized in little endian.

getWord64BE :: Unpacking Word64 Source

Get a Word64 serialized in big endian.

getBytes :: Int -> Unpacking ByteString Source

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 ByteString Source

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 ByteString Source

Get the remaining bytes.

getRemainingCopy :: Unpacking ByteString Source

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

getStorable :: Storable a => Unpacking a Source

Get an arbitrary type with the Storable class constraint.

The Storage method for sizeOf need to be constant size related to the type. It cannot use any fields to define its size.

The sizeOf method is always going to be called with undefined, so make sure sizeOf doesn't need the value of the type.

getFloat32LE :: Unpacking Float Source

Read a Float in little endian IEEE-754 format

getFloat32BE :: Unpacking Float Source

Read a Float in big endian IEEE-754 format

getFloat64LE :: Unpacking Double Source

Read a Double in little endian IEEE-754 format

getFloat64BE :: Unpacking Double Source

Read a Double in big endian IEEE-754 format

isolate :: Int -> Unpacking a -> Unpacking a Source

Isolate N bytes from the unpacking, and create an isolated context where only those N bytes are available.

If the sub unpacker doesn't consume all the bytes available, this function will raises an exception

endOfInput :: Unpacking Bool Source

Return True if there are no more bytes to be unpacked.

No input is consumed.

countRemaining :: Unpacking Int Source

Return the number of bytes remaining in the current Unpacking.

No input is consumed.

Packing functions

packGetPosition :: Packing Int Source

Get the position in the memory block.

putWord8 :: Word8 -> Packing () Source

Put a Word8

putHoleWord8 :: Packing (Hole Word8) Source

Put a Word8 Hole

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.

putHoleWord16 :: Packing (Hole Word16) Source

Put a Word16 Hole in host endian

putHoleWord16LE :: Packing (Hole Word16) Source

Put a Word16 Hole in little endian

putHoleWord16BE :: Packing (Hole Word16) Source

Put a Word16 Hole 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.

putFloat32LE :: Float -> Packing () Source

Write a Float in little endian IEEE-754 format

putFloat32BE :: Float -> Packing () Source

Write a Float in big endian IEEE-754 format

putFloat64LE :: Double -> Packing () Source

Write a Double in little endian IEEE-754 format

putFloat64BE :: Double -> Packing () Source

Write a Double in big endian IEEE-754 format

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

Fill a hole with a value

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