Foreign.Marshal.StaticArray

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 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 lifted 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)).

Documentation

type family Mutable a :: * -> * -> *

The Mutable type family is used to associate instances of IArray with instances of MArray that give non-copying unsafeFreeze. This is used to increase the efficiency of peek in StaticArray 's Storable instance.

If you're somehow using an instance of IArray other than Array or UArray, you'll need to add a type instance for your type. If it supports non-copying unsafeFreeze, the type instance should return the type constructor for the appropriate MArray instance. Otherwise, just have it return IOArray

data StaticArray backing dimensions elements

A minimal wrapper for instances of IArray 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 k1 backing dimensions elements)

Show (backing (Bound k dimensions) elements) => Show (StaticArray k k1 backing dimensions elements)

(StaticSize k d, Ix (Bound k d), Storable e, IArray b e, MArray (Mutable b) e IO) => Storable (StaticArray k * b d e)

staticArray :: (Ix (Bound d), IArray b e, StaticSize d) => [(Bound 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 StaticSize instance.

listStaticArray :: (StaticSize d, Ix (Bound 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.

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

Returns the backing Array of this StaticArray.

class StaticSize d where

This class connects dimension description types with IArray index types and values. Instances are provided for up to 13 dimensions as tuples. Additionally, there is support for unlimited dimensions via a list of dimensions. This results in nested pairs for the index type.

Associated Types

type Bound d :: *

The bounding type for this dimension description

Methods

extent :: StaticArray b d e -> (Bound d, Bound d)

The concrete bounds for an array of this dimensionality. Implementations of this function should not examine their argument in any way.

Instances

SingI Nat a => StaticSize Nat a

(SingI Nat n, StaticSize [Nat] (: Nat n2 ns)) => StaticSize [Nat] (: Nat n (: Nat n2 ns))

SingI Nat n => StaticSize [Nat] (: Nat n ([] Nat))

(SingI Nat a, SingI Nat b) => StaticSize ((,) Nat Nat) ((,) Nat Nat a b)

(SingI Nat a, SingI Nat b, SingI Nat c) => StaticSize ((,,) Nat Nat Nat) ((,,) Nat Nat Nat a b c)

(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)

(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)

(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)

(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)

(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)

(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)

(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)

(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)

(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)

(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)

fromNat :: forall proxy n. SingI n => proxy n -> Int

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.