-- 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:
--   
--   <ul>
--   <li>If you wrap a type in a <tt>newtype</tt>, then you can lift its
--   <a>Storable</a> instance to that <tt>newtype</tt> with the module
--   <a>Foreign.Storable.Newtype</a>. This way you do not need the
--   <tt>GeneralizedNewtypeDeriving</tt> feature of GHC.</li>
--   <li>If you have a type that is an instance of <a>Traversable</a>, you
--   can use that feature for implementation of <a>Storable</a> methods.
--   The module <a>Foreign.Storable.Traversable</a> allows manipulation of
--   the portion of your type, that is accessible by <a>Traversable</a>
--   methods. For instance with the type <tt>data T a = Cons Int [a]</tt>
--   and an according <a>Traversable</a> implementation, you can load and
--   store the elements of the contained list. This may be part of a
--   <a>Storable</a> implementation of the whole type.</li>
--   <li>If you have a record containing elements of various types, then
--   you need module <a>Foreign.Storable.Record</a>.</li>
--   </ul>
--   
--   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 <tt>storable-tuple</tt> and
--   <tt>sample-frame</tt>.
@package storable-record
@version 0.0.7

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:
--   
--   <pre>
--   import qualified 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
--   </pre>
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.
--   
--   <pre>
--   import Foreign.Storable.Record as Store
--   import Foreign.Storable (Storable (..), )
--   
--   import Control.Applicative (liftA2, )
--   
--   data Stereo a = Stereo {left, right :: a}
--   
--   store :: Storable a =&gt; Store.Dictionary (Stereo a)
--   store =
--      Store.run $
--      liftA2 Stereo
--         (Store.element left)
--         (Store.element right)
--   
--   instance (Storable a) =&gt; Storable (Stereo a) where
--      sizeOf = Store.sizeOf store
--      alignment = Store.alignment store
--      peek = Store.peek store
--      poke = Store.poke store
--   </pre>
--   
--   The <tt>Stereo</tt> constructor is exclusively used for constructing
--   the <tt>peek</tt> function, whereas the accessors in the
--   <tt>element</tt> calls are used for assembling the <tt>poke</tt>
--   function. It is required that the order of arguments of
--   <tt>Stereo</tt> matches the record accessors in the <tt>element</tt>
--   calls. If you want that the stored data correctly and fully represents
--   your Haskell data, it must hold:
--   
--   <pre>
--   Stereo (left x) (right x) = x   .
--   </pre>
--   
--   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 <tt>poke</tt> 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.Internal.Base.Applicative (Foreign.Storable.Record.Access r)
instance GHC.Internal.Base.Applicative (Foreign.Storable.Record.Box r)
instance GHC.Internal.Base.Functor (Foreign.Storable.Record.Access r)
instance GHC.Internal.Base.Functor (Foreign.Storable.Record.Box r)
instance GHC.Internal.Base.Monoid Foreign.Storable.Record.Alignment
instance GHC.Internal.Base.Semigroup Foreign.Storable.Record.Alignment


-- | Custom class for storing tuples and wrapper for storing tuples in
--   standard <a>Storable</a> class. These two solutions do not need orphan
--   instances. The package <tt>storable-tuple</tt> makes use of this
--   implementation.
module Foreign.Storable.Record.Tuple
class Storable a
sizeOf :: Storable a => a -> Int
alignment :: Storable a => a -> Int
peek :: Storable a => Ptr a -> IO a
poke :: Storable a => Ptr a -> a -> IO ()
newtype Tuple a
Tuple :: a -> Tuple a
[getTuple] :: Tuple a -> a
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Foreign.Storable.Record.Tuple.Tuple a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Foreign.Storable.Record.Tuple.Tuple a)
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Foreign.Storable.Record.Tuple.Tuple a)
instance Foreign.Storable.Record.Tuple.Storable a => GHC.Internal.Foreign.Storable.Storable (Foreign.Storable.Record.Tuple.Tuple a)
instance (GHC.Internal.Foreign.Storable.Storable a, GHC.Internal.Foreign.Storable.Storable b) => Foreign.Storable.Record.Tuple.Storable (a, b)
instance (GHC.Internal.Foreign.Storable.Storable a, GHC.Internal.Foreign.Storable.Storable b, GHC.Internal.Foreign.Storable.Storable c) => Foreign.Storable.Record.Tuple.Storable (a, b, c)
instance (GHC.Internal.Foreign.Storable.Storable a, GHC.Internal.Foreign.Storable.Storable b, GHC.Internal.Foreign.Storable.Storable c, GHC.Internal.Foreign.Storable.Storable d) => Foreign.Storable.Record.Tuple.Storable (a, b, c, d)


-- | If you have a <a>Traversable</a> instance of a record, you can load
--   and store all elements, that are accessible by <tt>Traversable</tt>
--   methods. We treat the record like an array, that is we assume, that
--   all elements have the same size and alignment.
--   
--   Example:
--   
--   <pre>
--   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) =&gt; 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
--   </pre>
--   
--   You would certainly not define the <a>Traversable</a> and according
--   instances just for the implementation of the <a>Storable</a> instance,
--   but there are usually similar applications where the
--   <tt>Traversable</tt> instance is useful.
module Foreign.Storable.Traversable
alignment :: (Foldable f, Storable a) => f a -> Int

-- | Warning: It uses Foldable class and will certainly access the data
--   structure and thus will fail on <a>undefined</a>.
--   
--   You may call it on the record, after re-constructing it lazily:
--   
--   <pre>
--   sizeOf . lazy
--   
--   lazy :: Complex a -&gt; Complex a
--   lazy ~(r:+i) = r:+i
--   </pre>
sizeOf :: (Foldable f, Storable a) => f a -> Int

-- | <tt>peek skeleton ptr</tt> fills the <tt>skeleton</tt> with data read
--   from memory beginning at <tt>ptr</tt>. The skeleton is needed formally
--   for using <a>Traversable</a>. 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 <tt>a</tt>. For example you can call
--   
--   <pre>
--   peek (replicate 10 ()) ptr
--   </pre>
--   
--   for reading 10 elements from memory starting at <tt>ptr</tt>.
peek :: (Traversable f, Storable a) => f () -> Ptr (f a) -> IO (f a)
poke :: (Foldable f, Storable a) => Ptr (f a) -> f a -> IO ()

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