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

-- | Elegant definition of Storable instances for records
--   
--   With this package you can build a Storable instance of a record type
--   from Storable instances of its elements in an elegant way. It does not
--   do any magic, just a bit arithmetic to compute the right offsets, that
--   would be otherwise done manually or by a preprocessor like C2HS. I
--   cannot promise that the generated memory layout is compatible with
--   that of a corresponding C struct. However, the module generates the
--   smallest layout that is possible with respect to the alignment of the
--   record elements. If you encounter, that a record does not have a
--   compatible layout, we should fix that. But also without C
--   compatibility this package is useful e.g. in connection with
--   StorableVector.
--   
--   We provide Storable instance support for several cases:
--   
--   
--   
- If you wrap a type in a newtype, then you can lift its
--   Storable instance to that newtype with the module
--   Foreign.Storable.Newtype. This way you do not need the
--   GeneralizedNewtypeDeriving feature of GHC.
--   
- If you have a type that is an instance of Traversable, you
--   can use that feature for implementation of Storable methods.
--   The module Foreign.Storable.Traversable allows manipulation of
--   the portion of your type, that is accessible by Traversable
--   methods. For instance with the type data T a = Cons Int [a]
--   and an according Traversable implementation, you can load and
--   store the elements of the contained list. This may be part of a
--   Storable implementation of the whole type.
--   
- If you have a record containing elements of various types, then
--   you need module Foreign.Storable.Record.
--   
--   
--   Note however that the Storable instances defined with this package are
--   quite slow in (up to) GHC-6.12.1. I'm afraid this is due to incomplete
--   inlining, but we have still to investigate the problem.
--   
--   For examples see packages storable-tuple and
--   sample-frame.
@package storable-record
@version 0.0.4

module Foreign.Storable.FixedArray
roundUp :: Int -> Int -> Int
sizeOfArray :: Storable a => Int -> a -> Int
pokeNext :: Storable a => a -> StateT (Ptr a) IO ()
peekNext :: Storable a => StateT (Ptr a) IO a
run :: Ptr (t a) -> StateT (Ptr a) IO c -> IO c

-- | Storable instances for simple wrapped types.
--   
--   Example:
--   
--   
--   import Foreign.Storable.Newtype as Store
--   
--   newtype MuLaw = MuLaw {deMuLaw :: Word8}
--   
--   instance Storable MuLaw where
--      sizeOf = Store.sizeOf deMuLaw
--      alignment = Store.alignment deMuLaw
--      peek = Store.peek MuLaw
--      poke = Store.poke deMuLaw
--   
module Foreign.Storable.Newtype
sizeOf :: Storable core => (wrapper -> core) -> wrapper -> Int
alignment :: Storable core => (wrapper -> core) -> wrapper -> Int
peek :: Storable core => (core -> wrapper) -> Ptr wrapper -> IO wrapper
poke :: Storable core => (wrapper -> core) -> Ptr wrapper -> wrapper -> IO ()

-- | Here we show an example of how to define a Storable instance with this
--   module.
--   
--   
--   import Foreign.Storable.Record as Store
--   import Foreign.Storable (Storable (..), )
--   
--   import Control.Applicative (liftA2, )
--   
--   data Stereo a = Stereo {left, right :: a}
--   
--   store :: Storable a => Store.Dictionary (Stereo a)
--   store =
--      Store.run $
--      liftA2 Stereo
--         (Store.element left)
--         (Store.element right)
--   
--   instance (Storable a) => Storable (Stereo a) where
--      sizeOf = Store.sizeOf store
--      alignment = Store.alignment store
--      peek = Store.peek store
--      poke = Store.poke store
--   
--   
--   The Stereo constructor is exclusively used for constructing
--   the peek function, whereas the accessors in the
--   element calls are used for assembling the poke
--   function. It is required that the order of arguments of
--   Stereo matches the record accessors in the element
--   calls. If you want that the stored data correctly and fully represents
--   your Haskell data, it must hold:
--   
--   
--   Stereo (left x) (right x) = x   .
--   
--   
--   Unfortunately this cannot be checked automatically. However,
--   mismatching types that are caused by swapped arguments are detected by
--   the type system. Our system performs for you: Size and alignment
--   computation, poking and peeking. Thus several inconsistency bugs can
--   be prevented using this package, like size mismatching the space
--   required by poke actions. There is no more restriction, thus
--   smart constructors and accessors and nested records work, too. For
--   nested records however, I recommend individual Storable instances for
--   the sub-records.
--   
--   You see it would simplify class instantiation if we could tell the
--   class dictionary at once instead of defining each method separately.
--   
--   In this implementation we tail pad records according to the overall
--   required alignment in conformance to the Linux/X86 ABI.
module Foreign.Storable.Record
data Dictionary r
data Access r a
element :: Storable a => (r -> a) -> Access r a
run :: Access r r -> Dictionary r
alignment :: Dictionary r -> r -> Int
sizeOf :: Dictionary r -> r -> Int
peek :: Dictionary r -> Ptr r -> IO r
poke :: Dictionary r -> Ptr r -> r -> IO ()
instance GHC.Base.Functor (Foreign.Storable.Record.Access r)
instance GHC.Base.Applicative (Foreign.Storable.Record.Access r)
instance GHC.Base.Semigroup Foreign.Storable.Record.Alignment
instance GHC.Base.Monoid Foreign.Storable.Record.Alignment
instance GHC.Base.Functor (Foreign.Storable.Record.Box r)
instance GHC.Base.Applicative (Foreign.Storable.Record.Box r)

-- | If you have a Traversable instance of a record, you can load
--   and store all elements, that are accessible by Traversable
--   methods. We treat the record like an array, that is we assume, that
--   all elements have the same size and alignment.
--   
--   Example:
--   
--   
--   import Foreign.Storable.Traversable as Store
--   
--   data Stereo a = Stereo {left, right :: a}
--   
--   instance Functor Stereo where
--      fmap = Trav.fmapDefault
--   
--   instance Foldable Stereo where
--      foldMap = Trav.foldMapDefault
--   
--   instance Traversable Stereo where
--      sequenceA ~(Stereo l r) = liftA2 Stereo l r
--   
--   instance (Storable a) => Storable (Stereo a) where
--      sizeOf = Store.sizeOf
--      alignment = Store.alignment
--      peek = Store.peek (error "instance Traversable Stereo is lazy, so we do not provide a real value here")
--      poke = Store.poke
--   
--   
--   You would certainly not define the Traversable and according
--   instances just for the implementation of the Storable instance,
--   but there are usually similar applications where the
--   Traversable instance is useful.
module Foreign.Storable.Traversable
alignment :: (Foldable f, Storable a) => f a -> Int
sizeOf :: (Foldable f, Storable a) => f a -> Int

-- | peek skeleton ptr fills the skeleton with data read
--   from memory beginning at ptr. The skeleton is needed formally
--   for using Traversable. For instance when reading a list, it is
--   not clear, how many elements shall be read. Using the skeleton you can
--   give this information and you also provide information that is not
--   contained in the element type a. For example you can call
--   
--   
--   peek (replicate 10 ()) ptr
--   
--   
--   for reading 10 elements from memory starting at ptr.
peek :: (Traversable f, Storable a) => f () -> Ptr (f a) -> IO (f a)
poke :: (Foldable f, Storable a) => Ptr (f a) -> f a -> IO ()

-- | Like peek but uses pure for construction of the result.
--   pure would be in class Pointed if that would exist.
--   Thus we use the closest approximate Applicative.
peekApplicative :: (Applicative f, Traversable f, Storable a) => Ptr (f a) -> IO (f a)
