-- 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.4.7

module Data.Store.Core

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

-- | Run the Poke action, with the Ptr to the buffer where
--   data is poked, and the current Offset. The result is the new
--   offset, along with a return value.
--   
--   May throw a PokeException, 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 poke. Note that other types of
--   exceptions could also be thrown. Invocations of fail in the
--   Poke monad causes this exception to be thrown.
--   
--   PokeExceptions 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 PokeException. These should be avoided when possible,
--   they usually indicate a programming error.
pokeException :: Text -> Poke a

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

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

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

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

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

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

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

-- | Holds a peekStatePtr, which is passed in to each Peek
--   action. If the package is built with the 'force-alignment' flag, this
--   also has a hidden Ptr 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 Poke and its length, uses it to fill a
--   ByteString
--   
--   This function is unsafe because the provided length must exactly match
--   the number of bytes used by the Poke. It will throw
--   PokeException 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 ByteString, potentially throwing
--   exceptions, and taking a Peek to run. It is an exception to not
--   consume all input.
decodeWith :: Peek a -> ByteString -> Either PeekException a

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

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

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

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

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

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

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

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

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

-- | Copy a section of memory, based on a ForeignPtr, 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 Ptr, 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 ByteArray#, 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

-- | Make a PokeState from a buffer pointer.
--   
--   The first argument is a pointer to the memory to write to. The second
--   argument is an IO action which is invoked if the store-core package
--   was built with the force-alignment flag. The action should
--   yield a pointer to scratch memory as large as
--   maybeAlignmentBufferSize.
--   
--   Since 0.4.2
unsafeMakePokeState :: Ptr Word8 -> IO (Ptr Word8) -> IO PokeState

-- | Make a PeekState from a buffer pointer.
--   
--   The first argument is a pointer to the memory to write to. The second
--   argument is an IO action which is invoked if the store-core package
--   was built with the force-alignment flag. The action should
--   yield a pointer to scratch memory as large as
--   maybeAlignmentBufferSize.
--   
--   Since 0.4.2
unsafeMakePeekState :: Ptr Word8 -> IO (Ptr Word8) -> IO PeekState

-- | If store-core is built with the force-alignment flag, then
--   this will be a Just value indicating the amount of memory that
--   is expected in the alignment buffer used by PeekState and
--   PokeState. Currently this will either be Just 32 or
--   Nothing.
maybeAlignmentBufferSize :: Maybe Int
instance GHC.Internal.Base.Applicative Data.Store.Core.Peek
instance GHC.Internal.Base.Applicative Data.Store.Core.Poke
instance GHC.Classes.Eq Data.Store.Core.PeekException
instance GHC.Classes.Eq Data.Store.Core.PokeException
instance GHC.Internal.Exception.Type.Exception Data.Store.Core.PeekException
instance GHC.Internal.Exception.Type.Exception Data.Store.Core.PokeException
instance GHC.Internal.Base.Functor Data.Store.Core.Peek
instance GHC.Internal.Base.Functor Data.Store.Core.PeekResult
instance GHC.Internal.Base.Functor Data.Store.Core.Poke
instance GHC.Internal.Control.Monad.Fail.MonadFail Data.Store.Core.Peek
instance GHC.Internal.Control.Monad.Fail.MonadFail Data.Store.Core.Poke
instance Control.Monad.IO.Class.MonadIO Data.Store.Core.Peek
instance Control.Monad.IO.Class.MonadIO Data.Store.Core.Poke
instance GHC.Internal.Base.Monad Data.Store.Core.Peek
instance GHC.Internal.Base.Monad Data.Store.Core.Poke
instance Control.Monad.Primitive.PrimMonad Data.Store.Core.Peek
instance GHC.Internal.Show.Show Data.Store.Core.PeekException
instance GHC.Internal.Show.Show Data.Store.Core.PokeException
