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


-- | Fast and lightweight binary serialization
--   
--   Fast and lightweight binary serialization
@package store-core
@version 0.4

module Data.Store.Core

-- | <a>Poke</a> actions are useful for building sequential serializers.
--   
--   They are actions which write values to bytes into memory specified by
--   a <a>Ptr</a> base. The <a>Applicative</a> and <a>Monad</a> instances
--   make it easy to write serializations, by keeping track of the
--   <a>Offset</a> of the current byte. They allow you to chain <a>Poke</a>
--   action such that subsequent <a>Poke</a>s write into subsequent
--   portions of the output.
newtype Poke a
Poke :: (PokeState -> Offset -> IO (Offset, a)) -> Poke a

-- | Run the <a>Poke</a> action, with the <a>Ptr</a> to the buffer where
--   data is poked, and the current <a>Offset</a>. The result is the new
--   offset, along with a return value.
--   
--   May throw a <a>PokeException</a>, though this should be avoided when
--   possible. They usually indicate a programming error.
[runPoke] :: Poke a -> PokeState -> Offset -> IO (Offset, a)

-- | Exception thrown while running <a>poke</a>. Note that other types of
--   exceptions could also be thrown. Invocations of <a>fail</a> in the
--   <a>Poke</a> monad causes this exception to be thrown.
--   
--   <a>PokeException</a>s are not expected to occur in ordinary
--   circumstances, and usually indicate a programming error.
data PokeException
PokeException :: Offset -> Text -> PokeException
[pokeExByteIndex] :: PokeException -> Offset
[pokeExMessage] :: PokeException -> Text

-- | Throws a <a>PokeException</a>. These should be avoided when possible,
--   they usually indicate a programming error.
pokeException :: Text -> Poke a

-- | <a>Peek</a> actions are useful for building sequential deserializers.
--   
--   They are actions which read from memory and construct values from it.
--   The <a>Applicative</a> and <a>Monad</a> instances make it easy to
--   chain these together to get more complicated deserializers. This
--   machinery keeps track of the current <a>Ptr</a> and end-of-buffer
--   <a>Ptr</a>.
newtype Peek a
Peek :: (PeekState -> Ptr Word8 -> IO (PeekResult a)) -> Peek a

-- | Run the <a>Peek</a> action, with a <a>Ptr</a> to the end of the buffer
--   where data is poked, and a <a>Ptr</a> to the current position. The
--   result is the <a>Ptr</a>, along with a return value.
--   
--   May throw a <a>PeekException</a> if the memory contains invalid
--   values.
[runPeek] :: Peek a -> PeekState -> Ptr Word8 -> IO (PeekResult a)

-- | A result of a <a>Peek</a> action containing the current <a>Ptr</a> and
--   a return value.
data PeekResult a
PeekResult :: {-# UNPACK #-} !(Ptr Word8) -> !a -> PeekResult a

-- | Exception thrown while running <a>peek</a>. Note that other types of
--   exceptions can also be thrown. Invocations of <a>fail</a> in the
--   <a>Poke</a> monad causes this exception to be thrown.
--   
--   <a>PeekException</a> is thrown when the data being decoded is invalid.
data PeekException
PeekException :: Offset -> Text -> PeekException
[peekExBytesFromEnd] :: PeekException -> Offset
[peekExMessage] :: PeekException -> Text

-- | Throws a <a>PeekException</a>.
peekException :: Text -> Peek a

-- | Throws a <a>PeekException</a> about an attempt to read too many bytes.
tooManyBytes :: Int -> Int -> String -> IO void

-- | Holds a <a>pokeStatePtr</a>, which is passed in to each <a>Poke</a>
--   action. If the package is built with the 'force-alignment' flag, this
--   also has a hidden <a>Ptr</a> field, which is used as scratch space
--   during unaligned writes.
data PokeState
pokeStatePtr :: PokeState -> Ptr Word8

-- | Holds a <tt>peekStatePtr</tt>, which is passed in to each <a>Peek</a>
--   action. If the package is built with the 'force-alignment' flag, this
--   also has a hidden <a>Ptr</a> field, which is used as scratch space
--   during unaligned reads.
data PeekState
peekStateEndPtr :: PeekState -> Ptr Word8

-- | How far into the given Ptr to look
type Offset = Int

-- | Given a <a>Poke</a> and its length, uses it to fill a
--   <a>ByteString</a>
--   
--   This function is unsafe because the provided length must exactly match
--   the number of bytes used by the <a>Poke</a>. It will throw
--   <a>PokeException</a> errors when the buffer is under or overshot.
--   However, in the case of overshooting the buffer, memory corruption and
--   segfaults may occur.
unsafeEncodeWith :: Poke () -> Int -> ByteString

-- | Decodes a value from a <a>ByteString</a>, potentially throwing
--   exceptions, and taking a <a>Peek</a> to run. It is an exception to not
--   consume all input.
decodeWith :: Peek a -> ByteString -> Either PeekException a

-- | Decodes a value from a <a>ByteString</a>, potentially throwing
--   exceptions, and taking a <a>Peek</a> to run. It is an exception to not
--   consume all input.
decodeExWith :: Peek a -> ByteString -> a

-- | Similar to <a>decodeExWith</a>, but it allows there to be more of the
--   buffer remaining. The <a>Offset</a> of the buffer contents immediately
--   after the decoded value is returned.
decodeExPortionWith :: Peek a -> ByteString -> (Offset, a)

-- | Decodes a value from a <a>ByteString</a>, potentially throwing
--   exceptions, and taking a <a>Peek</a> to run. It is an exception to not
--   consume all input.
decodeIOWith :: Peek a -> ByteString -> IO a

-- | Similar to <a>decodeExPortionWith</a>, but runs in the <a>IO</a>
--   monad.
decodeIOPortionWith :: Peek a -> ByteString -> IO (Offset, a)

-- | Like <a>decodeIOWith</a>, but using <a>Ptr</a> and length instead of a
--   <a>ByteString</a>.
decodeIOWithFromPtr :: Peek a -> Ptr Word8 -> Int -> IO a

-- | Like <a>decodeIOPortionWith</a>, but using <a>Ptr</a> and length
--   instead of a <a>ByteString</a>.
decodeIOPortionWithFromPtr :: Peek a -> Ptr Word8 -> Int -> IO (Offset, a)

-- | A <a>poke</a> implementation based on an instance of <a>Storable</a>.
pokeStorable :: Storable a => a -> Poke ()

-- | A <a>peek</a> implementation based on an instance of <a>Storable</a>
--   and <a>Typeable</a>.
peekStorable :: forall a. (Storable a, Typeable a) => Peek a

-- | A <a>peek</a> implementation based on an instance of <a>Storable</a>.
--   Use this if the type is not <a>Typeable</a>.
peekStorableTy :: forall a. Storable a => String -> Peek a

-- | Copy a section of memory, based on a <a>ForeignPtr</a>, to the output.
--   Note that this operation is unsafe, the offset and length parameters
--   are not checked.
pokeFromForeignPtr :: ForeignPtr a -> Int -> Int -> Poke ()

-- | Allocate a plain ForeignPtr (no finalizers), of the specified length
--   and fill it with bytes from the input.
peekToPlainForeignPtr :: String -> Int -> Peek (ForeignPtr a)

-- | Copy a section of memory, based on a <a>Ptr</a>, to the output. Note
--   that this operation is unsafe, because the offset and length
--   parameters are not checked.
pokeFromPtr :: Ptr a -> Int -> Int -> Poke ()

-- | Copy a section of memory, based on a <a>ByteArray#</a>, to the output.
--   Note that this operation is unsafe, because the offset and length
--   parameters are not checked.
pokeFromByteArray :: ByteArray# -> Int -> Int -> Poke ()

-- | Allocate a ByteArray of the specified length and fill it with bytes
--   from the input.
peekToByteArray :: String -> Int -> Peek ByteArray
instance GHC.Show.Show Data.Store.Core.PeekException
instance GHC.Classes.Eq Data.Store.Core.PeekException
instance GHC.Base.Functor Data.Store.Core.Peek
instance GHC.Base.Functor Data.Store.Core.PeekResult
instance GHC.Show.Show Data.Store.Core.PokeException
instance GHC.Classes.Eq Data.Store.Core.PokeException
instance GHC.Base.Functor Data.Store.Core.Poke
instance GHC.Base.Applicative Data.Store.Core.Poke
instance GHC.Base.Monad Data.Store.Core.Poke
instance Control.Monad.Fail.MonadFail Data.Store.Core.Poke
instance Control.Monad.IO.Class.MonadIO Data.Store.Core.Poke
instance GHC.Exception.Exception Data.Store.Core.PokeException
instance GHC.Base.Applicative Data.Store.Core.Peek
instance GHC.Base.Monad Data.Store.Core.Peek
instance Control.Monad.Fail.MonadFail Data.Store.Core.Peek
instance Control.Monad.Primitive.PrimMonad Data.Store.Core.Peek
instance Control.Monad.IO.Class.MonadIO Data.Store.Core.Peek
instance GHC.Exception.Exception Data.Store.Core.PeekException