Safe Haskell  None 

Language  Haskell2010 
Internal API for the store package. The functions here which are not reexported by Data.Store are less likely to have stable APIs.
This module also defines most of the included Store
instances, for
types from the base package and other commonly used packages
(bytestring, containers, text, time, etc).
Synopsis
 encode :: Store a => a > ByteString
 decode :: Store a => ByteString > Either PeekException a
 decodeWith :: Peek a > ByteString > Either PeekException a
 decodeEx :: Store a => ByteString > a
 decodeExWith :: Peek a > ByteString > a
 decodeExPortionWith :: Peek a > ByteString > (Offset, a)
 decodeIO :: Store a => ByteString > IO a
 decodeIOWith :: Peek a > ByteString > IO a
 decodeIOPortionWith :: Peek a > ByteString > IO (Offset, a)
 class Store a where
 data Poke a
 data Peek a
 runPeek :: Peek a > PeekState > Ptr Word8 > IO (PeekResult a)
 data PokeException = PokeException {}
 pokeException :: Text > Poke a
 data PeekException = PeekException {}
 peekException :: Text > Peek a
 tooManyBytes :: Int > Int > String > IO void
 data Size a
 getSize :: Store a => a > Int
 getSizeWith :: Size a > a > Int
 combineSize :: forall a b c. (Store a, Store b) => (c > a) > (c > b) > Size c
 combineSizeWith :: forall a b c. (c > a) > (c > b) > Size a > Size b > Size c
 addSize :: Int > Size a > Size a
 sizeSequence :: forall t. (IsSequence t, Store (Element t)) => Size t
 pokeSequence :: (IsSequence t, Store (Element t)) => t > Poke ()
 peekSequence :: (IsSequence t, Store (Element t), Index t ~ Int) => Peek t
 sizeSet :: forall t. (IsSet t, Store (Element t)) => Size t
 pokeSet :: (IsSet t, Store (Element t)) => t > Poke ()
 peekSet :: (IsSet t, Store (Element t)) => Peek t
 sizeMap :: forall t. (Store (ContainerKey t), Store (MapValue t), IsMap t) => Size t
 pokeMap :: (Store (ContainerKey t), Store (MapValue t), IsMap t) => t > Poke ()
 peekMap :: (Store (ContainerKey t), Store (MapValue t), IsMap t) => Peek t
 sizeOrdMap :: forall t. (Store (ContainerKey t), Store (MapValue t), IsMap t) => Size t
 pokeOrdMap :: (Store (ContainerKey t), Store (MapValue t), IsMap t) => t > Poke ()
 peekOrdMapWith :: (Store (ContainerKey t), Store (MapValue t)) => ([(ContainerKey t, MapValue t)] > t) > Peek t
 sizeArray :: (Ix i, IArray a e, Store i, Store e) => Size (a i e)
 pokeArray :: (Ix i, IArray a e, Store i, Store e) => a i e > Poke ()
 peekArray :: (Ix i, IArray a e, Store i, Store e) => Peek (a i e)
 class GStoreSize f
 genericSize :: (Generic a, GStoreSize (Rep a)) => Size a
 class GStorePoke f
 genericPoke :: (Generic a, GStorePoke (Rep a)) => a > Poke ()
 class GStorePeek f
 genericPeek :: (Generic a, GStorePeek (Rep a)) => Peek a
 skip :: Int > Peek ()
 isolate :: Int > Peek a > Peek a
 peekMagic :: (Eq a, Show a, Store a) => String > a > Peek ()
 class KnownNat n => IsStaticSize n a where
 toStaticSize :: a > Maybe (StaticSize n a)
 newtype StaticSize (n :: Nat) a = StaticSize {
 unStaticSize :: a
 toStaticSizeEx :: IsStaticSize n a => a > StaticSize n a
 liftStaticSize :: forall n a. (KnownNat n, Lift a) => TypeQ > StaticSize n a > ExpQ
 staticByteStringExp :: ByteString > ExpQ
Encoding and decoding strict ByteStrings.
encode :: Store a => a > ByteString Source #
Serializes a value to a ByteString
. In order to do this, it
first allocates a ByteString
of the correct size (based on
size
), and then uses poke
to fill it.
Safety of this function depends on correctness of the Store
instance. If size
returns a. The good news is that this isn't an
issue if you use welltested manual instances (such as those from
this package) combined with auomatic definition of instances.
decode :: Store a => ByteString > Either PeekException a Source #
Decodes a value from a ByteString
. Returns an exception if
there's an error while decoding, or if decoding undershoots /
overshoots the end of the buffer.
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.
decodeEx :: Store a => ByteString > a Source #
Decodes a value from a ByteString
, potentially throwing
exceptions. It is an exception to not consume all input.
decodeExWith :: Peek a > ByteString > 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.
decodeExPortionWith :: Peek a > ByteString > (Offset, 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.
decodeIO :: Store a => ByteString > IO a Source #
Decodes a value from a ByteString
, potentially throwing
exceptions. It is an exception to not consume all input.
decodeIOWith :: Peek a > ByteString > IO 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.
decodeIOPortionWith :: Peek a > ByteString > IO (Offset, a) #
Similar to decodeExPortionWith
, but runs in the IO
monad.
Store class and related types.
The Store
typeclass provides efficient serialization and
deserialization to raw pointer addresses.
The peek
and poke
methods should be defined such that
decodeEx (encode x) == x
.
Nothing
Yields the Size
of the buffer, in bytes, required to store
the encoded representation of the type.
Note that the correctness of this function is crucial for the
safety of poke
, as it does not do any bounds checking. It is
the responsibility of the invoker of poke
(encode
and similar
functions) to ensure that there's enough space in the output
buffer. If poke
writes beyond, then arbitrary memory can be
overwritten, causing undefined behavior and segmentation faults.
Serializes a value to bytes. It is the responsibility of the
caller to ensure that at least the number of bytes required by
size
are available. These details are handled by encode
and
similar utilities.
Serialized a value from bytes, throwing exceptions if it encounters invalid data or runs out of input bytes.
size :: (Generic a, GStoreSize (Rep a)) => Size a Source #
Yields the Size
of the buffer, in bytes, required to store
the encoded representation of the type.
Note that the correctness of this function is crucial for the
safety of poke
, as it does not do any bounds checking. It is
the responsibility of the invoker of poke
(encode
and similar
functions) to ensure that there's enough space in the output
buffer. If poke
writes beyond, then arbitrary memory can be
overwritten, causing undefined behavior and segmentation faults.
poke :: (Generic a, GStorePoke (Rep a)) => a > Poke () Source #
Serializes a value to bytes. It is the responsibility of the
caller to ensure that at least the number of bytes required by
size
are available. These details are handled by encode
and
similar utilities.
peek :: (Generic a, GStorePeek (Rep a)) => Peek a Source #
Serialized a value from bytes, throwing exceptions if it encounters invalid data or runs out of input bytes.
Instances
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
Poke
s write into subsequent portions of the output.
Instances
Monad Poke  
Functor Poke  
MonadFail Poke  
Defined in Data.Store.Core  
Applicative Poke  
MonadIO Poke  
Defined in Data.Store.Core 
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 endofbuffer Ptr
.
Instances
Monad Peek  
Functor Peek  
MonadFail Peek  
Defined in Data.Store.Core  
Applicative Peek  
MonadIO Peek  
Defined in Data.Store.Core  
PrimMonad Peek  
type PrimState Peek  
Defined in Data.Store.Core 
runPeek :: Peek a > PeekState > Ptr Word8 > IO (PeekResult 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.
Exceptions thrown by Poke
data PokeException #
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.
PokeException
s are not expected to occur in ordinary circumstances,
and usually indicate a programming error.
Instances
Eq PokeException  
Defined in Data.Store.Core (==) :: PokeException > PokeException > Bool # (/=) :: PokeException > PokeException > Bool #  
Show PokeException  
Defined in Data.Store.Core showsPrec :: Int > PokeException > ShowS # show :: PokeException > String # showList :: [PokeException] > ShowS #  
Exception PokeException  
Defined in Data.Store.Core 
pokeException :: Text > Poke a #
Throws a PokeException
. These should be avoided when possible,
they usually indicate a programming error.
Exceptions thrown by Peek
data PeekException #
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.
Instances
Eq PeekException  
Defined in Data.Store.Core (==) :: PeekException > PeekException > Bool # (/=) :: PeekException > PeekException > Bool #  
Show PeekException  
Defined in Data.Store.Core showsPrec :: Int > PeekException > ShowS # show :: PeekException > String # showList :: [PeekException] > ShowS #  
Exception PeekException  
Defined in Data.Store.Core 
peekException :: Text > Peek a #
Throws a PeekException
.
tooManyBytes :: Int > Int > String > IO void #
Throws a PeekException
about an attempt to read too many bytes.
Size type
Info about a type's serialized length. Either the length is known independently of the value, or the length depends on the value.
getSize :: Store a => a > Int Source #
Get the number of bytes needed to store the given value. See
size
.
getSizeWith :: Size a > a > Int Source #
Store instances in terms of IsSequence
sizeSequence :: forall t. (IsSequence t, Store (Element t)) => Size t Source #
Implement size
for an IsSequence
of Store
instances.
Note that many monomorphic containers have more efficient implementations (for example, via memcpy).
pokeSequence :: (IsSequence t, Store (Element t)) => t > Poke () Source #
Implement poke
for an IsSequence
of Store
instances.
Note that many monomorphic containers have more efficient implementations (for example, via memcpy).
peekSequence :: (IsSequence t, Store (Element t), Index t ~ Int) => Peek t Source #
Implement peek
for an IsSequence
of Store
instances.
Note that many monomorphic containers have more efficient implementations (for example, via memcpy).
Store instances in terms of IsSet
pokeSet :: (IsSet t, Store (Element t)) => t > Poke () Source #
Implement poke
for an IsSequence
of Store
instances.
peekSet :: (IsSet t, Store (Element t)) => Peek t Source #
Implement peek
for an IsSequence
of Store
instances.
Store instances in terms of IsMap
sizeMap :: forall t. (Store (ContainerKey t), Store (MapValue t), IsMap t) => Size t Source #
Implement size
for an IsMap
of where both ContainerKey
and
MapValue
are Store
instances.
pokeMap :: (Store (ContainerKey t), Store (MapValue t), IsMap t) => t > Poke () Source #
Implement poke
for an IsMap
of where both ContainerKey
and
MapValue
are Store
instances.
peekMap :: (Store (ContainerKey t), Store (MapValue t), IsMap t) => Peek t Source #
Implement peek
for an IsMap
of where both ContainerKey
and
MapValue
are Store
instances.
Utilities for ordered maps
sizeOrdMap :: forall t. (Store (ContainerKey t), Store (MapValue t), IsMap t) => Size t Source #
pokeOrdMap :: (Store (ContainerKey t), Store (MapValue t), IsMap t) => t > Poke () Source #
:: (Store (ContainerKey t), Store (MapValue t))  
=> ([(ContainerKey t, MapValue t)] > t)  A function to construct the map from an ascending list such as

> Peek t 
Decode the results of pokeOrdMap
using a given function to construct
the map.
Store instances in terms of IArray
Store instances in terms of Generic
class GStoreSize f Source #
gsize
Instances
GStoreSize (V1 :: Type > Type) Source #  
Defined in Data.Store.Impl  
GStoreSize (U1 :: Type > Type) Source #  
Defined in Data.Store.Impl  
Store a => GStoreSize (K1 i a :: Type > Type) Source #  
Defined in Data.Store.Impl  
(FitsInByte (SumArity (a :+: b)), GStoreSizeSum 0 (a :+: b)) => GStoreSize (a :+: b) Source #  
Defined in Data.Store.Impl  
(GStoreSize a, GStoreSize b) => GStoreSize (a :*: b) Source #  
Defined in Data.Store.Impl  
GStoreSize f => GStoreSize (M1 i c f) Source #  
Defined in Data.Store.Impl 
genericSize :: (Generic a, GStoreSize (Rep a)) => Size a Source #
class GStorePoke f Source #
gpoke
Instances
GStorePoke (V1 :: Type > Type) Source #  
Defined in Data.Store.Impl  
GStorePoke (U1 :: Type > Type) Source #  
Defined in Data.Store.Impl  
Store a => GStorePoke (K1 i a :: Type > Type) Source #  
Defined in Data.Store.Impl  
(FitsInByte (SumArity (a :+: b)), GStorePokeSum 0 (a :+: b)) => GStorePoke (a :+: b) Source #  
Defined in Data.Store.Impl  
(GStorePoke a, GStorePoke b) => GStorePoke (a :*: b) Source #  
Defined in Data.Store.Impl  
GStorePoke f => GStorePoke (M1 i c f) Source #  
Defined in Data.Store.Impl 
genericPoke :: (Generic a, GStorePoke (Rep a)) => a > Poke () Source #
class GStorePeek f Source #
gpeek
Instances
GStorePeek (V1 :: Type > Type) Source #  
Defined in Data.Store.Impl  
GStorePeek (U1 :: Type > Type) Source #  
Defined in Data.Store.Impl  
Store a => GStorePeek (K1 i a :: Type > Type) Source #  
Defined in Data.Store.Impl  
(FitsInByte (SumArity (a :+: b)), GStorePeekSum 0 (a :+: b)) => GStorePeek (a :+: b) Source #  
Defined in Data.Store.Impl  
(GStorePeek a, GStorePeek b) => GStorePeek (a :*: b) Source #  
Defined in Data.Store.Impl  
GStorePeek f => GStorePeek (M1 i c f) Source #  
Defined in Data.Store.Impl 
genericPeek :: (Generic a, GStorePeek (Rep a)) => Peek a Source #
Peek utilities
isolate :: Int > Peek a > Peek a Source #
Isolate the input to n bytes, skipping n bytes forward. Fails if m
advances the offset beyond the isolated region.
peekMagic :: (Eq a, Show a, Store a) => String > a > Peek () Source #
Ensure the presence of a given magic value.
Throws a PeekException
if the value isn't present.
Static Size type
class KnownNat n => IsStaticSize n a where Source #
toStaticSize :: a > Maybe (StaticSize n a) Source #
Instances
KnownNat n => IsStaticSize n ByteString Source #  
Defined in Data.Store.Internal toStaticSize :: ByteString > Maybe (StaticSize n ByteString) Source # 
newtype StaticSize (n :: Nat) a Source #
StaticSize  

Instances
Eq a => Eq (StaticSize n a) Source #  
Defined in Data.Store.Internal (==) :: StaticSize n a > StaticSize n a > Bool # (/=) :: StaticSize n a > StaticSize n a > Bool #  
(KnownNat n, Data a) => Data (StaticSize n a) Source #  
Defined in Data.Store.Internal gfoldl :: (forall d b. Data d => c (d > b) > d > c b) > (forall g. g > c g) > StaticSize n a > c (StaticSize n a) # gunfold :: (forall b r. Data b => c (b > r) > c r) > (forall r. r > c r) > Constr > c (StaticSize n a) # toConstr :: StaticSize n a > Constr # dataTypeOf :: StaticSize n a > DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) > Maybe (c (StaticSize n a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) > Maybe (c (StaticSize n a)) # gmapT :: (forall b. Data b => b > b) > StaticSize n a > StaticSize n a # gmapQl :: (r > r' > r) > r > (forall d. Data d => d > r') > StaticSize n a > r # gmapQr :: (r' > r > r) > r > (forall d. Data d => d > r') > StaticSize n a > r # gmapQ :: (forall d. Data d => d > u) > StaticSize n a > [u] # gmapQi :: Int > (forall d. Data d => d > u) > StaticSize n a > u # gmapM :: Monad m => (forall d. Data d => d > m d) > StaticSize n a > m (StaticSize n a) # gmapMp :: MonadPlus m => (forall d. Data d => d > m d) > StaticSize n a > m (StaticSize n a) # gmapMo :: MonadPlus m => (forall d. Data d => d > m d) > StaticSize n a > m (StaticSize n a) #  
Ord a => Ord (StaticSize n a) Source #  
Defined in Data.Store.Internal compare :: StaticSize n a > StaticSize n a > Ordering # (<) :: StaticSize n a > StaticSize n a > Bool # (<=) :: StaticSize n a > StaticSize n a > Bool # (>) :: StaticSize n a > StaticSize n a > Bool # (>=) :: StaticSize n a > StaticSize n a > Bool # max :: StaticSize n a > StaticSize n a > StaticSize n a # min :: StaticSize n a > StaticSize n a > StaticSize n a #  
Show a => Show (StaticSize n a) Source #  
Defined in Data.Store.Internal showsPrec :: Int > StaticSize n a > ShowS # show :: StaticSize n a > String # showList :: [StaticSize n a] > ShowS #  
Generic (StaticSize n a) Source #  
Defined in Data.Store.Internal type Rep (StaticSize n a) :: Type > Type # from :: StaticSize n a > Rep (StaticSize n a) x # to :: Rep (StaticSize n a) x > StaticSize n a #  
NFData a => NFData (StaticSize n a) Source #  
Defined in Data.Store.Internal rnf :: StaticSize n a > () #  
KnownNat n => Store (StaticSize n ByteString) Source #  
Defined in Data.Store.Internal size :: Size (StaticSize n ByteString) Source # poke :: StaticSize n ByteString > Poke () Source # peek :: Peek (StaticSize n ByteString) Source #  
type Rep (StaticSize n a) Source #  
Defined in Data.Store.Internal type Rep (StaticSize n a) = D1 (MetaData "StaticSize" "Data.Store.Internal" "store0.7.22jPBCCtCGxXLxLi6t9f2XS" True) (C1 (MetaCons "StaticSize" PrefixI True) (S1 (MetaSel (Just "unStaticSize") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a))) 
toStaticSizeEx :: IsStaticSize n a => a > StaticSize n a Source #
liftStaticSize :: forall n a. (KnownNat n, Lift a) => TypeQ > StaticSize n a > ExpQ Source #
staticByteStringExp :: ByteString > ExpQ Source #