Foreign.Marshal.StaticArray

This module defines StaticArray, a simple wrapper around arrays with their dimensions in the type. StaticArray provides Storable instances using the type-level dimensions. This eases writing FFI bindings to fixed-size native arrays. For example, StaticArray UArray 10 CInt has a Storable instance that is directly compatible with int foo[10] in native code.

Multidimensional native arrays are also supported. StaticArray UArray '(10,20,100) CUChar is compatible with unsigned 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) CUChar is a UArray (Int, Int, Int) CUChar with its bounds set to ((0,0,0),(9,19,99)).

Basic interface

data StaticArray backing dimensions elements

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 (Index k dimensions) elements) => Eq (StaticArray k backing dimensions elements)

(IArray b e, IxStatic k d, Show e) => Show (StaticArray k b d e)

(IxStatic k d, Storable e) => Storable (StaticArray k Array d e)

(IxStatic k d, Storable e, IArray UArray e, MArray IOUArray e IO) => Storable (StaticArray k UArray d e)

toArray :: StaticArray backing dimensions elements -> backing (Index dimensions) elements

Returns the backing value of this StaticArray.

staticBounds :: forall b d e. IxStatic d => StaticArray b d e -> (Index d, Index d)

Get the compile-time bounds from a StaticArray. Does not examine its argument.

staticArray :: (IArray b e, IxStatic d) => [(Index d, e)] -> StaticArray b d e

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 IxStatic instance.

listStaticArray :: (IxStatic d, IArray b e) => [e] -> StaticArray b d e

Create a new StaticArray from a list of elements in index order. Implemented in terms of listArray, with the same caveats.

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 a minimum complete, correct Storable implementation for StaticArray. They can be used to add more instances of Storable, if required. 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. (IxStatic d, Storable e) => StaticArray b d e -> Int

Get the size, in bytes, of the native representation of this StaticArray.

alignment' :: forall b d e. Storable e => StaticArray b d e -> Int

Get the alignment, in bytes, of the native representation of this StaticArray

poke' :: forall b d e. (IxStatic d, IArray b e, Storable e) => Ptr (StaticArray b d e) -> StaticArray b d e -> IO ()

Write the contents of this StaticArray to the given location in memory.

peek' :: forall b d e m. (IxStatic d, Storable e, IArray b e, MArray m e IO) => (m (Index d) e -> IO (b (Index d) e)) -> Ptr (StaticArray b d e) -> IO (StaticArray b d e)

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.