Safe Haskell | None |
---|
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,
has a StaticArray
UArray
10 CIntStorable
instance that is directly compatible with int foo[10]
in native
code.
Multidimensional native arrays are also supported.
is compatible with 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
is a
StaticArray
UArray
'(10,20,100) CUChar
with its bounds set to
UArray
(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.
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.
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.