| Safe Haskell | None |
|---|
Foreign.Marshal.StaticArray
Description
This module defines StaticArray, a simple wrapper around instances
of IArray with its dimensions encoded in the type. StaticArray
provides a Storable instance that uses the type-level dimensions,
and significantly eases writing FFI bindings to fixed-size native
arrays. For example, StaticArray UArray 10 CIntStorable
instance that is directly compatible with int foo[10] in native
code.
Multidimensional native arrays are also supported. StaticArray
UArray '(10,20,100) CUCharunsigned char
foo[10][20][100]. Note the leading ' before the tuple containing
the dimensions. It marks it as a DataKinds promoted tuple, necessary
to store the dimensions.
To operate on the contents of a StaticArray, use
toArray. toArray returns the backing array with the correct type
and index values already in place. For example, the result of
toArray on a StaticArray UArray '(10,20,100) CUCharUArray (Int, Int, Int) CUChar((0,0,0),(9,19,99)).
- data StaticArray backing dimensions elements
- toArray :: StaticArray backing dimensions elements -> backing (Bound dimensions) elements
- staticArray :: (Ix (Bound d), IArray b e, StaticSize d) => [(Bound d, e)] -> StaticArray b d e
- listStaticArray :: (StaticSize d, Ix (Bound d), IArray b e) => [e] -> StaticArray b d e
- sizeOf' :: forall b d e. (StaticSize d, Ix (Bound d), Storable e) => StaticArray b d e -> Int
- alignment' :: forall b d e. Storable e => StaticArray b d e -> Int
- poke' :: forall b d e. (Ix (Bound d), IArray b e, Storable e) => Ptr (StaticArray b d e) -> StaticArray b d e -> IO ()
- peek' :: forall b d e m. (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)
- fromNat :: forall proxy n. SingI n => proxy n -> Int
- class StaticSize d where
- type Bound d :: *
- extent :: StaticArray b d e -> (Bound d, Bound d)
Basic interface
data StaticArray backing dimensions elements Source
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.
Instances
| Eq (backing (Bound k dimensions) elements) => Eq (StaticArray k backing dimensions elements) | |
| (IArray b e, Ix (Bound k d), Show e) => Show (StaticArray k b d e) | |
| (StaticSize k d, Ix (Bound k d), Storable e) => Storable (StaticArray k Array d e) | |
| (StaticSize k d, Ix (Bound k d), Storable e, IArray UArray e, MArray IOUArray e IO) => Storable (StaticArray k UArray d e) |
toArray :: StaticArray backing dimensions elements -> backing (Bound dimensions) elementsSource
Returns the backing Array of this StaticArray.
staticArray :: (Ix (Bound d), IArray b e, StaticSize d) => [(Bound d, e)] -> StaticArray b d eSource
Create a new StaticArray from a list of indices and
elements. This has all the semantic caveats of array, except that
the bounds are as good as those provided by the StaticSize
instance.
listStaticArray :: (StaticSize d, Ix (Bound d), IArray b e) => [e] -> StaticArray b d eSource
Create a new StaticArray from a list of elements in index
order. Implemented in terms of listArray.
Adding new Storable instances
This module only has Storable instances for UArray
and Array as backing types. This is the result of
ensuring that peek is not implemented with an additional
copy. The mutable temporary array needs to have a
representation compatible with that of the result array to
avoid that extra copy.
The following functions provide correct implementations of
a minimum complete Storable implementation for
StaticArray. The helper function required by peek' is
the part necessary for efficient implementations which
prevent creation of a fully polymorphic instance.
sizeOf' :: forall b d e. (StaticSize d, Ix (Bound d), Storable e) => StaticArray b d e -> IntSource
Get the size, in bytes, of the native representation of this
StaticArray.
alignment' :: forall b d e. Storable e => StaticArray b d e -> IntSource
Get the alignment, in bytes, of the native representation of this
StaticArray
poke' :: forall b d e. (Ix (Bound d), IArray b e, Storable e) => Ptr (StaticArray b d e) -> StaticArray b d e -> IO ()Source
Write the contents of this StaticArray to the given location in
memory.
peek' :: forall b d e m. (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)Source
Create a new StaticArray 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 unsafeFreeze
are safe as this argument, and preferred.
Adding new StaticSize instances
This module contains instances of StaticSize for types
of kind Nat, types of the promoted kind '[Nat], and
promoted tuples of Nat up to 13 elements. For instances
not relying on promoted data types, see the
Foreign.Marshal.StaticArray.Unpromoted module.
fromNat :: forall proxy n. SingI n => proxy n -> IntSource
A conversion function for converting type-level naturals to
value-level. This is being exposed to aid in the creation of
additional StaticSize instances for those who might desire to do
so.
Haddock is currently eating the important qualification that the
type variable n must have the kind Nat. The SingI instance is
automatically fulfilled for all types of kind Nat. Its explicit
presence in the signature is an artifact of how GHC implements
dictionary passing and type erasure.
class StaticSize d whereSource
This class connects dimension description types with IArray
index types and values.
Methods
extent :: StaticArray b d e -> (Bound d, Bound d)Source
The concrete bounds for an array of this dimensionality. Implementations of this function should not examine their argument in any way.
Instances