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


-- | Statically-sized array wrappers with Storable instances
for FFI marshaling
--   
--   Uses type-level numeric literals to wrap arrays in a type that
--   statically fixes their size. The wrapper has a <tt>Storable</tt>
--   instance, for easy integration with fixed-size native arrays.
@package storable-static-array
@version 0.5.0.0


-- | This module defines <a>StaticArray</a>, a simple wrapper around
--   instances of <a>IArray</a> with its dimensions encoded in the type.
--   <a>StaticArray</a> provides a <a>Storable</a> instance that uses the
--   type-level dimensions, and significantly eases writing FFI bindings to
--   fixed-size native arrays. For example, <tt><a>StaticArray</a>
--   <a>UArray</a> 10 CInt</tt> has a <a>Storable</a> instance that is
--   directly compatible with <tt>int foo[10]</tt> in native code.
--   
--   Multidimensional native arrays are also supported.
--   <tt><a>StaticArray</a> <a>UArray</a> '(10,20,100) CUChar</tt> is
--   compatible with <tt>unsigned char foo[10][20][100]</tt>. Note the
--   leading <tt>'</tt> before the tuple containing the dimensions. It
--   marks it as a <tt>DataKinds</tt> promoted tuple, necessary to store
--   the dimensions.
--   
--   To operate on the contents of a <a>StaticArray</a>, use
--   <a>toArray</a>. <a>toArray</a> returns the backing array with the
--   correct type and index values already in place. For example, the
--   result of <a>toArray</a> on a <tt><a>StaticArray</a> <a>UArray</a>
--   '(10,20,100) CUChar</tt> is a <tt><a>UArray</a> (Int, Int, Int)
--   CUChar</tt> with its bounds set to <tt>((0,0,0),(9,19,99))</tt>.
module Foreign.Marshal.StaticArray

-- | A minimal array wrapper that encodes the full dimensions of the array
--   in the type. Intended for interfacing with (possibly-)multidimensional
--   arrays of fixed size in native code.
--   
--   The constructor is not exported to prevent creating a StaticArray with
--   a size that doesn't match its dimensions.
data StaticArray backing dimensions (elements :: *)

-- | Returns the backing <a>Array</a> of this <a>StaticArray</a>.
toArray :: StaticArray backing dimensions elements -> backing (Bound dimensions) elements

-- | Create a new <a>StaticArray</a> from a list of indices and elements.
--   This has all the semantic caveats of <a>array</a>, except that the
--   bounds are as good as those provided by the <a>StaticSize</a>
--   instance.
staticArray :: (Ix (Bound d), IArray b e, StaticSize d) => [(Bound d, e)] -> StaticArray b d e

-- | Create a new <a>StaticArray</a> from a list of elements in index
--   order. Implemented in terms of <a>listArray</a>.
listStaticArray :: (StaticSize d, Ix (Bound d), IArray b e) => [e] -> StaticArray b d e

-- | Get the size, in bytes, of the native representation of this
--   <a>StaticArray</a>.
sizeOf' :: (StaticSize d, Ix (Bound d), Storable e) => StaticArray b d e -> Int

-- | Get the alignment, in bytes, of the native representation of this
--   <a>StaticArray</a>
alignment' :: Storable e => StaticArray b d e -> Int

-- | Write the contents of this <a>StaticArray</a> to the given location in
--   memory.
poke' :: (Ix (Bound d), IArray b e, Storable e) => Ptr (StaticArray b d e) -> StaticArray b d e -> IO ()

-- | Create a new <a>StaticArray</a> from the contents of the given
--   location in memory. Uses a temporary mutable array to build up the
--   result, then freezes it. The first argument is the freezing function.
--   Non-copying implementations of <a>unsafeFreeze</a> are safe as this
--   argument, and preferred.
peek' :: (StaticSize d, Ix (Bound d), Storable e, IArray b e, MArray m e IO) => (m (Bound d) e -> IO (b (Bound d) e)) -> Ptr (StaticArray b d e) -> IO (StaticArray b d e)

-- | A conversion function for converting type-level naturals to
--   value-level. This is being exposed to aid in the creation of
--   additional <a>StaticSize</a> instances for those who might desire to
--   do so.
--   
--   Haddock is currently eating the important qualification that the type
--   variable <tt>n</tt> must have the kind <a>Nat</a>. The <a>SingI</a>
--   instance is automatically fulfilled for all types of kind <a>Nat</a>.
--   Its explicit presence in the signature is an artifact of how GHC
--   implements dictionary passing and type erasure.
fromNat :: SingI n => proxy n -> Int

-- | This class connects dimension description types with <a>IArray</a>
--   index types and values.
class StaticSize d where type family Bound d :: *
extent :: StaticSize d => StaticArray b d e -> (Bound d, Bound d)
instance Eq (backing (Bound k dimensions) elements) => Eq (StaticArray k backing dimensions elements)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j, SingI Nat k, SingI Nat l, SingI Nat m) => StaticSize ((,,,,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat) ('(,,,,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat a b c d e f g h i j k l m)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j, SingI Nat k, SingI Nat l) => StaticSize ((,,,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat) ('(,,,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat a b c d e f g h i j k l)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j, SingI Nat k) => StaticSize ((,,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat) ('(,,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat a b c d e f g h i j k)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j) => StaticSize ((,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat) ('(,,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat Nat a b c d e f g h i j)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i) => StaticSize ((,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat) ('(,,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat Nat a b c d e f g h i)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h) => StaticSize ((,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat) ('(,,,,,,,) Nat Nat Nat Nat Nat Nat Nat Nat a b c d e f g h)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g) => StaticSize ((,,,,,,) Nat Nat Nat Nat Nat Nat Nat) ('(,,,,,,) Nat Nat Nat Nat Nat Nat Nat a b c d e f g)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f) => StaticSize ((,,,,,) Nat Nat Nat Nat Nat Nat) ('(,,,,,) Nat Nat Nat Nat Nat Nat a b c d e f)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e) => StaticSize ((,,,,) Nat Nat Nat Nat Nat) ('(,,,,) Nat Nat Nat Nat Nat a b c d e)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d) => StaticSize ((,,,) Nat Nat Nat Nat) ('(,,,) Nat Nat Nat Nat a b c d)
instance (SingI Nat a, SingI Nat b, SingI Nat c) => StaticSize ((,,) Nat Nat Nat) ('(,,) Nat Nat Nat a b c)
instance (SingI Nat a, SingI Nat b) => StaticSize ((,) Nat Nat) ('(,) Nat Nat a b)
instance SingI Nat a => StaticSize Nat a
instance (SingI Nat n, StaticSize [Nat] ((':) Nat n2 ns)) => StaticSize [Nat] ((':) Nat n ((':) Nat n2 ns))
instance SingI Nat n => StaticSize [Nat] ((':) Nat n ('[] Nat))
instance (StaticSize k d, Ix (Bound k d), Storable e) => Storable (StaticArray k Array d e)
instance (StaticSize k d, Ix (Bound k d), Storable e, IArray UArray e, MArray IOUArray e IO) => Storable (StaticArray k UArray d e)
instance (IArray b e, Ix (Bound k d), Show e) => Show (StaticArray k b d e)


-- | This module contains a collection of data types for describing
--   dimensions of <a>StaticArray</a> that do not depend on promoted lists
--   and tuples.
--   
--   For convenience, it re-exports all of
--   <a>Foreign.Marshal.StaticArray</a>.
module Foreign.Marshal.StaticArray.Unpromoted

-- | <a>:.</a> is provided as an alternative means of constructing a
--   type-level list of dimensions. <tt>DataKinds</tt>-promoted lists are
--   also supported and easier to use in almost all cases. The exception is
--   when <tt>CPP</tt> is involved, when a single <tt>'</tt> on a line
--   causes <tt>CPP</tt> to fail.
--   
--   With <tt>TypeOperators</tt> and <tt>DataKinds</tt> enabled,
--   <tt><a>StaticArray</a> <tt>UArray</tt> (2:.10:.25:.<a>Nil</a>)
--   <a>Int</a></tt> is equivalent to <tt><a>StaticArray</a>
--   <tt>UArray</tt> '[2,10,25] <a>Int</a></tt> and both wrap a
--   <tt><tt>UArray</tt> (<a>Int</a>,(<a>Int</a>,<a>Int</a>))
--   <a>Int</a></tt> with bounds <tt>((0,(0,0)),(1,(9,24)))</tt>.
--   
--   Neither promoted lists nor this approach support creating
--   0-dimensional arrays, because they make no sense with
--   <tt>Storable</tt>.
data (:.) a b

-- | <a>Nil</a> is the terminator for type-level lists created with
--   <a>:.</a>
data Nil

-- | An alternative dimension type to promoted pairs, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D2 (a :: Nat) (b :: Nat)

-- | An alternative dimension type to promoted triples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D3 (a :: Nat) (b :: Nat) (c :: Nat)

-- | An alternative dimension type to promoted 4-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D4 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat)

-- | An alternative dimension type to promoted 5-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D5 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat)

-- | An alternative dimension type to promoted 6-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D6 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat)

-- | An alternative dimension type to promoted 7-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D7 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat) (g :: Nat)

-- | An alternative dimension type to promoted 8-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D8 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat) (g :: Nat) (h :: Nat)

-- | An alternative dimension type to promoted 9-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D9 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat) (g :: Nat) (h :: Nat) (i :: Nat)

-- | An alternative dimension type to promoted 10-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D10 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat) (g :: Nat) (h :: Nat) (i :: Nat) (j :: Nat)

-- | An alternative dimension type to promoted 11-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D11 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat) (g :: Nat) (h :: Nat) (i :: Nat) (j :: Nat) (k :: Nat)

-- | An alternative dimension type to promoted 12-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D12 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat) (g :: Nat) (h :: Nat) (i :: Nat) (j :: Nat) (k :: Nat) (l :: Nat)

-- | An alternative dimension type to promoted 13-tuples, provided for
--   syntactic compatibility with <tt>CPP</tt>.
data D13 (a :: Nat) (b :: Nat) (c :: Nat) (d :: Nat) (e :: Nat) (f :: Nat) (g :: Nat) (h :: Nat) (i :: Nat) (j :: Nat) (k :: Nat) (l :: Nat) (m :: Nat)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j, SingI Nat k, SingI Nat l, SingI Nat m) => StaticSize * (D13 a b c d e f g h i j k l m)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j, SingI Nat k, SingI Nat l) => StaticSize * (D12 a b c d e f g h i j k l)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j, SingI Nat k) => StaticSize * (D11 a b c d e f g h i j k)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i, SingI Nat j) => StaticSize * (D10 a b c d e f g h i j)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h, SingI Nat i) => StaticSize * (D9 a b c d e f g h i)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g, SingI Nat h) => StaticSize * (D8 a b c d e f g h)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f, SingI Nat g) => StaticSize * (D7 a b c d e f g)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e, SingI Nat f) => StaticSize * (D6 a b c d e f)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d, SingI Nat e) => StaticSize * (D5 a b c d e)
instance (SingI Nat a, SingI Nat b, SingI Nat c, SingI Nat d) => StaticSize * (D4 a b c d)
instance (SingI Nat a, SingI Nat b, SingI Nat c) => StaticSize * (D3 a b c)
instance (SingI Nat a, SingI Nat b) => StaticSize * (D2 a b)
instance (SingI Nat n, StaticSize * ((:.) k k1 n2 ns)) => StaticSize * ((:.) Nat * n ((:.) k k1 n2 ns))
instance SingI Nat n => StaticSize * ((:.) Nat * n Nil)