-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Short description -- -- Please see the README on GitHub at -- https://github.com/lehins/mempack#readme @package mempack @version 0.1.0.0 module Data.MemPack.Buffer -- | Immutable memory buffer class Buffer b bufferByteCount :: Buffer b => b -> Int buffer :: Buffer b => b -> (ByteArray# -> a) -> (Addr# -> a) -> a newMutableByteArray :: Bool -> Int -> ST s (MutableByteArray s) freezeMutableByteArray :: MutableByteArray d -> ST d ByteArray -- | It is ok to use ByteString withing ST, as long as underlying pointer -- is never mutated or returned from the supplied action. withPtrByteStringST :: ByteString -> (Ptr a -> ST s b) -> ST s b pinnedByteArrayToByteString :: ByteArray -> ByteString pinnedByteArrayToForeignPtr :: ByteArray# -> ForeignPtr a byteArrayToShortByteString :: ByteArray -> ShortByteString byteArrayFromShortByteString :: ShortByteString -> ByteArray instance Data.MemPack.Buffer.Buffer Data.Array.Byte.ByteArray instance Data.MemPack.Buffer.Buffer Data.ByteString.Short.Internal.ShortByteString instance Data.MemPack.Buffer.Buffer Data.ByteString.Internal.Type.ByteString module Data.MemPack.Error data SomeError [SomeError] :: (Typeable e, Error e) => e -> SomeError -- | Very similar interface to Exceptions, except not intended for -- run time exceptions. class Show e => Error e toSomeError :: Error e => e -> SomeError toSomeError :: (Error e, Typeable e) => e -> SomeError fromSomeError :: Error e => SomeError -> Maybe e fromSomeError :: (Error e, Typeable e) => SomeError -> Maybe e newtype TextError TextError :: Text -> TextError newtype ManyErrors ManyErrors :: NonEmpty SomeError -> ManyErrors data UnknownError UnknownError :: UnknownError fromMultipleErrors :: [SomeError] -> SomeError data RanOutOfBytesError RanOutOfBytesError :: Int -> Int -> Int -> RanOutOfBytesError [ranOutOfBytesRead] :: RanOutOfBytesError -> Int [ranOutOfBytesAvailable] :: RanOutOfBytesError -> Int [ranOutOfBytesRequested] :: RanOutOfBytesError -> Int data NotFullyConsumedError NotFullyConsumedError :: Int -> Int -> String -> NotFullyConsumedError [notFullyConsumedRead] :: NotFullyConsumedError -> Int [notFullyConsumedAvailable] :: NotFullyConsumedError -> Int [notFullyConsumedTypeName] :: NotFullyConsumedError -> String showBytes :: Int -> String instance Data.String.IsString Data.MemPack.Error.TextError instance GHC.Show.Show Data.MemPack.Error.TextError instance GHC.Classes.Eq Data.MemPack.Error.TextError instance GHC.Show.Show Data.MemPack.Error.ManyErrors instance GHC.Show.Show Data.MemPack.Error.UnknownError instance GHC.Classes.Ord Data.MemPack.Error.RanOutOfBytesError instance GHC.Classes.Eq Data.MemPack.Error.RanOutOfBytesError instance GHC.Classes.Ord Data.MemPack.Error.NotFullyConsumedError instance GHC.Classes.Eq Data.MemPack.Error.NotFullyConsumedError instance GHC.Show.Show Data.MemPack.Error.NotFullyConsumedError instance Data.MemPack.Error.Error Data.MemPack.Error.NotFullyConsumedError instance GHC.Show.Show Data.MemPack.Error.RanOutOfBytesError instance Data.MemPack.Error.Error Data.MemPack.Error.RanOutOfBytesError instance Data.MemPack.Error.Error Data.MemPack.Error.UnknownError instance Data.MemPack.Error.Error Data.MemPack.Error.ManyErrors instance Data.MemPack.Error.Error Data.MemPack.Error.TextError instance Data.String.IsString Data.MemPack.Error.SomeError instance GHC.Show.Show Data.MemPack.Error.SomeError instance GHC.Exception.Type.Exception Data.MemPack.Error.SomeError instance Data.MemPack.Error.Error Data.MemPack.Error.SomeError module Data.MemPack -- | Monad that is used for serializing data into a -- MutableByteArray. It is based on StateT that tracks the -- current index into the MutableByteArray where next write is -- expected to happen. newtype Pack s a Pack :: (MutableByteArray s -> StateT Int (ST s) a) -> Pack s a [runPack] :: Pack s a -> MutableByteArray s -> StateT Int (ST s) a -- | Monad that is used for deserializing data from a memory Buffer. -- It is based on StateT that tracks the current index into the -- Buffer a, from where the next read suppose to happen. -- Unpacking can fail with MonadFail instance or with -- failUnpack that provides a more type safe way of failing using -- Error interface. newtype Unpack b a Unpack :: (b -> StateT Int (Fail SomeError) a) -> Unpack b a [runUnpack] :: Unpack b a -> b -> StateT Int (Fail SomeError) a -- | Efficient serialization interface that operates directly on memory -- buffers. class MemPack a -- | Name of the type that is being deserialized for error reporting. -- Default implementation relies on Typeable. typeName :: MemPack a => String -- | Name of the type that is being deserialized for error reporting. -- Default implementation relies on Typeable. typeName :: (MemPack a, Typeable a) => String -- | Report the exact size in number of bytes that packed version of this -- type will occupy. It is very important to get this right, otherwise -- packM will result in a runtime exception. Another words this is -- the expected property that it should hold: -- -- 
--   packedByteCount a == bufferByteCount (pack a)
--
packedByteCount :: MemPack a => a -> Int -- | Write binary representation of a type into the MutableByteArray -- which can be accessed with ask, whenever direct operations on -- it are necessary. packM :: MemPack a => a -> Pack s () -- | Read binary representation of the type directly from the buffer, which -- can be accessed with ask when necessary. Direct reads from the -- buffer should be preceded with advancing the buffer offset with -- MonadState by the number of bytes that will be consumed from -- the buffer and making sure that no reads outside of the buffer can -- happen. Violation of these rules will lead to segfaults. unpackM :: (MemPack a, Buffer b) => Unpack b a -- | Serialize a type into an unpinned ByteArray -- --

Examples

-- -- 
--   >>> :set -XTypeApplications
--   
--   >>> unpack @[Int] $ pack ([1,2,3,4,5] :: [Int])
--   Right [1,2,3,4,5]
--
pack :: forall a. (MemPack a, HasCallStack) => a -> ByteArray -- | Same as pack, but allows controlling the pinnedness of -- allocated memory packByteArray :: forall a. (MemPack a, HasCallStack) => Bool -> a -> ByteArray -- | Serialize a type into a pinned ByteString packByteString :: forall a. (MemPack a, HasCallStack) => a -> ByteString -- | Serialize a type into an unpinned ShortByteString packShortByteString :: forall a. (MemPack a, HasCallStack) => a -> ShortByteString -- | Same as packByteArray, but produces a mutable array instead packMutableByteArray :: forall a s. (MemPack a, HasCallStack) => Bool -> a -> ST s (MutableByteArray s) -- | Increment the offset counter of Pack monad by then number of -- packedByteCount and return the starting offset. packIncrement :: MemPack a => a -> Pack s Int -- | Increment the offset counter of Unpack monad by the supplied -- number of bytes. Returns the original offset or fails with -- RanOutOfBytesError whenever there is not enough bytes in the -- Buffer. guardAdvanceUnpack :: Buffer b => Int -> Unpack b Int -- | Unpack a memory Buffer into a type using its MemPack -- instance. Besides potential unpacking failures due to a malformed -- buffer it will also fail the supplied Buffer was not fully -- consumed. Use unpackLeftOver, whenever a partially consumed -- buffer is possible. unpack :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Either SomeError a -- | Same as unpack except fails in a Fail monad, instead of -- Either. unpackFail :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Fail SomeError a -- | Same as unpackFail except fails in any MonadFail, -- instead of Fail. unpackMonadFail :: forall a b m. (MemPack a, Buffer b, MonadFail m) => b -> m a -- | Same as unpack except throws a runtime exception upon a failure unpackError :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> a -- | Unpack a memory Buffer into a type using its MemPack -- instance. Besides the unpacked type it also returns an index into a -- buffer where unpacked has stopped. unpackLeftOver :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Fail SomeError (a, Int) -- | Failing unpacking with an Error. failUnpack :: Error e => e -> Unpack b a -- | This is the implementation of unpackM for ByteArray and -- ByteString unpackByteArray :: Buffer b => Bool -> Unpack b ByteArray -- | Variable length encoding for bounded types. This type of encoding will -- use less memory for small values, but for larger values it will -- consume more memory and will be slower during packing/unpacking. newtype VarLen a VarLen :: a -> VarLen a [unVarLen] :: VarLen a -> a -- | This is a helper type useful for serializing number of elements in -- data structures. It uses VarLen underneath, since sizes of -- common data structures aren't too big. It also prevents negative -- values from being serialized and deserialized. newtype Length Length :: Int -> Length [unLength] :: Length -> Int -- | This is a helper type that is useful for creating MemPack -- instances for sum types. newtype Tag Tag :: Word8 -> Tag [unTag] :: Tag -> Word8 packTagM :: Tag -> Pack s () unpackTagM :: Buffer b => Unpack b Tag unknownTagM :: forall a m b. (MemPack a, MonadFail m) => Tag -> m b packedTagByteCount :: Int -- | Tail recursive version of replicateM replicateTailM :: Monad m => Int -> m a -> m [a] lift_# :: (State# s -> State# s) -> Pack s () st_ :: (State# s -> State# s) -> ST s () -- | A state transformer monad parameterized by: -- -- -- -- The return function leaves the state unchanged, while -- >>= uses the final state of the first computation as -- the initial state of the second. newtype () => StateT s (m :: Type -> Type) a StateT :: (s -> m (a, s)) -> StateT s (m :: Type -> Type) a [runStateT] :: StateT s (m :: Type -> Type) a -> s -> m (a, s) -- | Fail monad transformer that plays well with MonadFail type -- class. newtype () => FailT e (m :: Type -> Type) a FailT :: m (Either [e] a) -> FailT e (m :: Type -> Type) a instance GHC.Bits.FiniteBits a => GHC.Bits.FiniteBits (Data.MemPack.VarLen a) instance GHC.Bits.Bits a => GHC.Bits.Bits (Data.MemPack.VarLen a) instance GHC.Real.Integral a => GHC.Real.Integral (Data.MemPack.VarLen a) instance GHC.Real.Real a => GHC.Real.Real (Data.MemPack.VarLen a) instance GHC.Num.Num a => GHC.Num.Num (Data.MemPack.VarLen a) instance GHC.Enum.Enum a => GHC.Enum.Enum (Data.MemPack.VarLen a) instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Data.MemPack.VarLen a) instance GHC.Show.Show a => GHC.Show.Show (Data.MemPack.VarLen a) instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.MemPack.VarLen a) instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.MemPack.VarLen a) instance GHC.Num.Num Data.MemPack.Length instance GHC.Show.Show Data.MemPack.Length instance GHC.Classes.Eq Data.MemPack.Length instance GHC.Enum.Bounded Data.MemPack.Tag instance GHC.Enum.Enum Data.MemPack.Tag instance GHC.Num.Num Data.MemPack.Tag instance GHC.Show.Show Data.MemPack.Tag instance GHC.Classes.Ord Data.MemPack.Tag instance GHC.Classes.Eq Data.MemPack.Tag instance Data.MemPack.MemPack Data.MemPack.Tag instance Data.MemPack.MemPack a => Data.MemPack.MemPack [a] instance Data.MemPack.MemPack Data.Array.Byte.ByteArray instance Data.MemPack.MemPack Data.ByteString.Short.Internal.ShortByteString instance Data.MemPack.MemPack Data.ByteString.Internal.Type.ByteString instance GHC.Enum.Bounded Data.MemPack.Length instance GHC.Enum.Enum Data.MemPack.Length instance Data.MemPack.MemPack Data.MemPack.Length instance Data.MemPack.MemPack (Data.MemPack.VarLen GHC.Word.Word16) instance Data.MemPack.MemPack (Data.MemPack.VarLen GHC.Word.Word32) instance Data.MemPack.MemPack (Data.MemPack.VarLen GHC.Word.Word64) instance Data.MemPack.MemPack (Data.MemPack.VarLen GHC.Types.Word) instance Data.MemPack.MemPack () instance Data.MemPack.MemPack GHC.Types.Bool instance Data.MemPack.MemPack a => Data.MemPack.MemPack (GHC.Maybe.Maybe a) instance (Data.MemPack.MemPack a, Data.MemPack.MemPack b) => Data.MemPack.MemPack (Data.Either.Either a b) instance Data.MemPack.MemPack GHC.Types.Char instance Data.MemPack.MemPack GHC.Types.Float instance Data.MemPack.MemPack GHC.Types.Double instance Data.MemPack.MemPack (GHC.Ptr.Ptr a) instance Data.MemPack.MemPack (GHC.Stable.StablePtr a) instance Data.MemPack.MemPack GHC.Types.Int instance Data.MemPack.MemPack GHC.Int.Int8 instance Data.MemPack.MemPack GHC.Int.Int16 instance Data.MemPack.MemPack GHC.Int.Int32 instance Data.MemPack.MemPack GHC.Int.Int64 instance Data.MemPack.MemPack GHC.Types.Word instance Data.MemPack.MemPack GHC.Word.Word8 instance Data.MemPack.MemPack GHC.Word.Word16 instance Data.MemPack.MemPack GHC.Word.Word32 instance Data.MemPack.MemPack GHC.Word.Word64 instance Data.MemPack.MemPack GHC.Num.Integer.Integer instance Data.MemPack.MemPack GHC.Num.Natural.Natural instance Data.MemPack.MemPack a => Data.MemPack.MemPack (Data.Complex.Complex a) instance (Data.MemPack.MemPack a, GHC.Real.Integral a) => Data.MemPack.MemPack (GHC.Real.Ratio a) instance (Data.MemPack.MemPack a, Data.MemPack.MemPack b) => Data.MemPack.MemPack (a, b) instance (Data.MemPack.MemPack a, Data.MemPack.MemPack b, Data.MemPack.MemPack c) => Data.MemPack.MemPack (a, b, c) instance (Data.MemPack.MemPack a, Data.MemPack.MemPack b, Data.MemPack.MemPack c, Data.MemPack.MemPack d) => Data.MemPack.MemPack (a, b, c, d) instance (Data.MemPack.MemPack a, Data.MemPack.MemPack b, Data.MemPack.MemPack c, Data.MemPack.MemPack d, Data.MemPack.MemPack e) => Data.MemPack.MemPack (a, b, c, d, e) instance (Data.MemPack.MemPack a, Data.MemPack.MemPack b, Data.MemPack.MemPack c, Data.MemPack.MemPack d, Data.MemPack.MemPack e, Data.MemPack.MemPack f) => Data.MemPack.MemPack (a, b, c, d, e, f) instance (Data.MemPack.MemPack a, Data.MemPack.MemPack b, Data.MemPack.MemPack c, Data.MemPack.MemPack d, Data.MemPack.MemPack e, Data.MemPack.MemPack f, Data.MemPack.MemPack g) => Data.MemPack.MemPack (a, b, c, d, e, f, g) instance GHC.Base.Functor (Data.MemPack.Unpack s) instance GHC.Base.Applicative (Data.MemPack.Unpack b) instance GHC.Base.Monad (Data.MemPack.Unpack b) instance Control.Monad.Fail.MonadFail (Data.MemPack.Unpack b) instance Control.Monad.Reader.Class.MonadReader b (Data.MemPack.Unpack b) instance Control.Monad.State.Class.MonadState GHC.Types.Int (Data.MemPack.Unpack b) instance GHC.Base.Alternative (Data.MemPack.Unpack b) instance GHC.Base.Functor (Data.MemPack.Pack s) instance GHC.Base.Applicative (Data.MemPack.Pack s) instance GHC.Base.Monad (Data.MemPack.Pack s) instance Control.Monad.Reader.Class.MonadReader (Data.Array.Byte.MutableByteArray s) (Data.MemPack.Pack s) instance Control.Monad.State.Class.MonadState GHC.Types.Int (Data.MemPack.Pack s)