-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Fast byte serializer and unserializer
--   
@package packer
@version 0.1.6


-- | Access to lower primitive that allow to use Packing and Unpacking, on
--   mmap type of memory. Potentially unsafe, as it can't check if any of
--   value passed are valid.
module Data.Packer.Unsafe

-- | Run packing on an arbitrary buffer with a size.
--   
--   This is available, for example to run on mmap typed memory, and this
--   is highly unsafe, as the user need to make sure the pointer and size
--   passed to this function are correct.
runPackingAt :: Ptr Word8 -> Int -> Packing a -> IO (a, Int)

-- | Run unpacking on an arbitrary buffer with a size.
--   
--   This is available, for example to run on mmap typed memory, and this
--   is highly unsafe, as the user need to make sure the pointer and size
--   passed to this function are correct.
runUnpackingAt :: ForeignPtr Word8 -> Int -> Int -> Unpacking a -> IO a


module Data.Packer.IO

-- | Run packing with a buffer created internally with a monadic action and
--   return the bytestring
runPackingIO :: Int -> Packing a -> IO (a, ByteString)

-- | Unpack a bytestring using a monadic unpack action in the IO monad.
runUnpackingIO :: ByteString -> Unpacking a -> IO a

-- | Similar to <a>runUnpackingIO</a> but catch exception and return an
--   Either type.
tryUnpackingIO :: ByteString -> Unpacking a -> IO (Either SomeException a)


-- | Simple packing module.
--   
--   This is a tradeoff between a more pure / builder (binary, cereal,
--   builder) and direct access to Storable or pointer manipulation
module Data.Packer

-- | Packing monad
data Packing a

-- | Unpacking monad
data Unpacking a

-- | Exception when trying to get bytes out of the memory bounds.
data OutOfBoundUnpacking
OutOfBoundUnpacking :: Int -> Int -> OutOfBoundUnpacking

-- | Exception when trying to put bytes out of the memory bounds.
data OutOfBoundPacking
OutOfBoundPacking :: Int -> Int -> OutOfBoundPacking

-- | Exception when isolate doesn't consume all the bytes passed in the sub
--   unpacker
data IsolationNotFullyConsumed
IsolationNotFullyConsumed :: Int -> Int -> IsolationNotFullyConsumed

-- | 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.
data Hole a

-- | Unpack a bytestring using a monadic unpack action.
runUnpacking :: Unpacking a -> ByteString -> a

-- | Similar to <a>runUnpacking</a> but returns an Either type with an
--   exception type in case of failure.
tryUnpacking :: Unpacking a -> ByteString -> Either SomeException a

-- | Run packing with a buffer created internally with a monadic action and
--   return the bytestring
runPacking :: Int -> Packing a -> ByteString

-- | Run packing with a buffer created internally with a monadic action and
--   return the bytestring
runPackingRes :: Int -> Packing a -> (a, ByteString)

-- | Skip bytes
unpackSkip :: Int -> Unpacking ()

-- | 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.
unpackSetPosition :: Int -> Unpacking ()

-- | Get the position in the memory block.
unpackGetPosition :: Unpacking Int

-- | Get a Word8
getWord8 :: Unpacking Word8

-- | Get a Word16 in the host endianess.
--   
--   It's recommended to use an explicit endianness (LE or BE) when
--   unserializing format.
getWord16 :: Unpacking Word16

-- | Get a Word16 serialized in little endian.
getWord16LE :: Unpacking Word16

-- | Get a Word16 serialized in big endian.
getWord16BE :: Unpacking Word16

-- | Get a Word32 in the host endianess.
--   
--   It's recommended to use an explicit endianness (LE or BE) when
--   unserializing format.
getWord32 :: Unpacking Word32

-- | Get a Word32 serialized in little endian.
getWord32LE :: Unpacking Word32

-- | Get a Word32 serialized in big endian.
getWord32BE :: Unpacking Word32

-- | Get a Word64 in the host endianess.
--   
--   It's recommended to use an explicit endianness (LE or BE) when
--   unserializing format.
getWord64 :: Unpacking Word64

-- | Get a Word64 serialized in little endian.
getWord64LE :: Unpacking Word64

-- | Get a Word64 serialized in big endian.
getWord64BE :: Unpacking Word64

-- | 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.
getBytes :: Int -> Unpacking ByteString

-- | Similar to <a>getBytes</a> 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.
getBytesCopy :: Int -> Unpacking ByteString

-- | Get a number of bytes until in bytestring format.
--   
--   this could be made more efficient
getBytesWhile :: (Word8 -> Bool) -> Unpacking (Maybe ByteString)

-- | Get the remaining bytes.
getRemaining :: Unpacking ByteString

-- | Get the remaining bytes but copy the bytestring and drop any reference
--   from the original function.
getRemainingCopy :: Unpacking ByteString

-- | 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.
getStorable :: Storable a => Unpacking a

-- | Read a Float in little endian IEEE-754 format
getFloat32LE :: Unpacking Float

-- | Read a Float in big endian IEEE-754 format
getFloat32BE :: Unpacking Float

-- | Read a Double in little endian IEEE-754 format
getFloat64LE :: Unpacking Double

-- | Read a Double in big endian IEEE-754 format
getFloat64BE :: Unpacking Double

-- | 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
isolate :: Int -> Unpacking a -> Unpacking a

-- | Get the position in the memory block.
packGetPosition :: Packing Int

-- | Put a Word8
putWord8 :: Word8 -> Packing ()

-- | Put a Word8 Hole
putHoleWord8 :: Packing (Hole Word8)

-- | Put a Word16 in the host endianess.
--   
--   It's recommended to use an explicit endianness (LE or BE) when
--   serializing format.
putWord16 :: Word16 -> Packing ()

-- | Put a Word16 serialized in little endian.
putWord16LE :: Word16 -> Packing ()

-- | Put a Word16 serialized in big endian.
putWord16BE :: Word16 -> Packing ()

-- | Put a Word16 Hole in host endian
putHoleWord16 :: Packing (Hole Word16)

-- | Put a Word16 Hole in little endian
putHoleWord16LE :: Packing (Hole Word16)

-- | Put a Word16 Hole in big endian
putHoleWord16BE :: Packing (Hole Word16)

-- | Put a Word32 in the host endianess.
--   
--   It's recommended to use an explicit endianness (LE or BE) when
--   serializing format.
putWord32 :: Word32 -> Packing ()

-- | Put a Word32 serialized in little endian.
putWord32LE :: Word32 -> Packing ()

-- | Put a Word32 serialized in big endian.
putWord32BE :: Word32 -> Packing ()

-- | Put a Word32 Hole in host endian
putHoleWord32 :: Packing (Hole Word32)

-- | Put a Word32 Hole in little endian
putHoleWord32LE :: Packing (Hole Word32)

-- | Put a Word32 Hole in big endian
putHoleWord32BE :: Packing (Hole Word32)

-- | Put a Word64 in the host endianess.
--   
--   It's recommended to use an explicit endianness (LE or BE) when
--   serializing format.
putWord64 :: Word64 -> Packing ()

-- | Put a Word64 serialized in little endian.
putWord64LE :: Word64 -> Packing ()

-- | Put a Word64 serialized in big endian.
putWord64BE :: Word64 -> Packing ()

-- | Put a Word64 Hole in host endian
putHoleWord64 :: Packing (Hole Word64)

-- | Put a Word64 Hole in little endian
putHoleWord64LE :: Packing (Hole Word64)

-- | Put a Word64 Hole in big endian
putHoleWord64BE :: Packing (Hole Word64)

-- | Put a Bytestring.
putBytes :: ByteString -> Packing ()

-- | Put an arbitrary type with the Storable class constraint.
putStorable :: Storable a => a -> Packing ()

-- | Write a Float in little endian IEEE-754 format
putFloat32LE :: Float -> Packing ()

-- | Write a Float in big endian IEEE-754 format
putFloat32BE :: Float -> Packing ()

-- | Write a Double in little endian IEEE-754 format
putFloat64LE :: Double -> Packing ()

-- | Write a Double in big endian IEEE-754 format
putFloat64BE :: Double -> Packing ()

-- | Fill a hole with a value
--   
--   TODO: user can use one hole many times leading to wrong counting.
fillHole :: Hole a -> a -> Packing ()