| License | BSD-style |
|---|---|
| Maintainer | Vincent Hanquez <vincent@snarc.org> |
| Stability | experimental |
| Portability | unknown |
| Safe Haskell | None |
| Language | Haskell98 |
Data.Packer
Description
Simple packing module.
This is a tradeoff between a more pure / builder (binary, cereal, builder) and direct access to Storable or pointer manipulation
- data Packing a
- data Unpacking a
- data OutOfBoundUnpacking = OutOfBoundUnpacking Int Int
- data OutOfBoundPacking = OutOfBoundPacking Int Int
- data IsolationNotFullyConsumed = IsolationNotFullyConsumed Int Int
- data Hole a
- runUnpacking :: Unpacking a -> ByteString -> a
- tryUnpacking :: Unpacking a -> ByteString -> Either SomeException a
- runPacking :: Int -> Packing a -> ByteString
- runPackingRes :: Int -> Packing a -> (a, ByteString)
- unpackSkip :: Int -> Unpacking ()
- unpackSetPosition :: Int -> Unpacking ()
- unpackGetPosition :: Unpacking Int
- getWord8 :: Unpacking Word8
- getWord16 :: Unpacking Word16
- getWord16LE :: Unpacking Word16
- getWord16BE :: Unpacking Word16
- getWord32 :: Unpacking Word32
- getWord32LE :: Unpacking Word32
- getWord32BE :: Unpacking Word32
- getWord64 :: Unpacking Word64
- getWord64LE :: Unpacking Word64
- getWord64BE :: Unpacking Word64
- getBytes :: Int -> Unpacking ByteString
- getBytesCopy :: Int -> Unpacking ByteString
- getBytesWhile :: (Word8 -> Bool) -> Unpacking (Maybe ByteString)
- getRemaining :: Unpacking ByteString
- getRemainingCopy :: Unpacking ByteString
- getStorable :: Storable a => Unpacking a
- getFloat32LE :: Unpacking Float
- getFloat32BE :: Unpacking Float
- getFloat64LE :: Unpacking Double
- getFloat64BE :: Unpacking Double
- isolate :: Int -> Unpacking a -> Unpacking a
- endOfInput :: Unpacking Bool
- countRemaining :: Unpacking Int
- packGetPosition :: Packing Int
- putWord8 :: Word8 -> Packing ()
- putHoleWord8 :: Packing (Hole Word8)
- putWord16 :: Word16 -> Packing ()
- putWord16LE :: Word16 -> Packing ()
- putWord16BE :: Word16 -> Packing ()
- putHoleWord16 :: Packing (Hole Word16)
- putHoleWord16LE :: Packing (Hole Word16)
- putHoleWord16BE :: Packing (Hole Word16)
- putWord32 :: Word32 -> Packing ()
- putWord32LE :: Word32 -> Packing ()
- putWord32BE :: Word32 -> Packing ()
- putHoleWord32 :: Packing (Hole Word32)
- putHoleWord32LE :: Packing (Hole Word32)
- putHoleWord32BE :: Packing (Hole Word32)
- putWord64 :: Word64 -> Packing ()
- putWord64LE :: Word64 -> Packing ()
- putWord64BE :: Word64 -> Packing ()
- putHoleWord64 :: Packing (Hole Word64)
- putHoleWord64LE :: Packing (Hole Word64)
- putHoleWord64BE :: Packing (Hole Word64)
- putBytes :: ByteString -> Packing ()
- putStorable :: Storable a => a -> Packing ()
- putFloat32LE :: Float -> Packing ()
- putFloat32BE :: Float -> Packing ()
- putFloat64LE :: Double -> Packing ()
- putFloat64BE :: Double -> Packing ()
- fillHole :: Hole a -> a -> Packing ()
Types
Packing monad
Unpacking monad
data OutOfBoundUnpacking Source
Exception when trying to get bytes out of the memory bounds.
Constructors
| OutOfBoundUnpacking Int Int |
data OutOfBoundPacking Source
Exception when trying to put bytes out of the memory bounds.
Constructors
| OutOfBoundPacking Int Int |
data IsolationNotFullyConsumed Source
Exception when isolate doesn't consume all the bytes passed in the sub unpacker
Constructors
| IsolationNotFullyConsumed Int Int |
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.
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