Data.Array.CArray.Base

This module provides both the immutable CArray and mutable IOCArray. The underlying storage is exactly the same - pinned memory on the GC'd heap. Elements are stored according to the class Storable. You can obtain a pointer to the array contents to manipulate elements from languages like C.

CArray is 16-byte aligned by default. If you create a CArray with unsafeForeignPtrToCArray then it may not be aligned. This will be an issue if you intend to use SIMD instructions.

CArray is similar to UArray but slower if you stay within Haskell. CArray can handle more types and can be used by external libraries.

IOCArray is equivalent to StorableArray and similar to IOUArray but slower. IOCArray has O(1) versions of unsafeFreeze and unsafeThaw when converting to/from CArray.

Documentation

data CArray i e

The immutable array type.

Constructors

CArray !i !i Int !(ForeignPtr e)

Instances

Typeable2 CArray

Storable e => IArray CArray e

(Ix ix, Eq e, Storable e) => Eq (CArray ix e)

(Data i, Data e) => Data (CArray i e)

(Ix ix, Ord e, Storable e) => Ord (CArray ix e)

(Ix ix, Show ix, Show e, Storable e) => Show (CArray ix e)

(Ix i, Binary i, Binary e, Storable e) => Binary (CArray i e)

data IOCArray i e

Absolutely equivalent representation, but used for the mutable interface.

Constructors

IOCArray !i !i Int !(ForeignPtr e)

Instances

Typeable2 IOCArray

Storable e => MArray IOCArray e IO

(Data i, Data e) => Data (IOCArray i e)

withCArray :: CArray i e -> (Ptr e -> IO a) -> IO a

The pointer to the array contents is obtained by withCArray. The idea is similar to ForeignPtr (used internally here). The pointer should be used only during execution of the IO action retured by the function passed as argument to withCArray.

withIOCArray :: IOCArray i e -> (Ptr e -> IO a) -> IO a

touchIOCArray :: IOCArray i e -> IO ()

If you want to use it afterwards, ensure that you touchCArray after the last use of the pointer, so the array is not freed too early.

unsafeForeignPtrToCArray :: Ix i => ForeignPtr e -> (i, i) -> IO (CArray i e)

O(1) Construct a CArray from an arbitrary ForeignPtr. It is the caller's responsibility to ensure that the ForeignPtr points to an area of memory sufficient for the specified bounds.

unsafeForeignPtrToIOCArray :: Ix i => ForeignPtr e -> (i, i) -> IO (IOCArray i e)

O(1) Construct a CArray from an arbitrary ForeignPtr. It is the caller's responsibility to ensure that the ForeignPtr points to an area of memory sufficient for the specified bounds.

toForeignPtr :: CArray i e -> (Int, ForeignPtr e)

O(1) Extract ForeignPtr from a CArray.

unsafeCArrayToByteString :: Storable e => CArray i e -> ByteString

O(1) Turn a CArray into a ByteString. Unsafe because it uses castForeignPtr and thus is not platform independent.

unsafeByteStringToCArray :: (Ix i, Storable e) => (i, i) -> ByteString -> Maybe (CArray i e)

O(1) Turn a ByteString into a CArray. Unsafe because it uses castForeignPtr and thus is not platform independent. Returns Nothing if the range specified is larger than the size of the ByteString or the start of the ByteString does not fulfil the alignment requirement of the resulting CArray (as specified by the Storable instance).

copy :: (Ix i, Storable e) => CArray i e -> IO (CArray i e)

freezeIOCArray :: (Ix i, Storable e) => IOCArray i e -> IO (CArray i e)

unsafeFreezeIOCArray :: Ix i => IOCArray i e -> IO (CArray i e)

thawIOCArray :: (Ix i, Storable e) => CArray i e -> IO (IOCArray i e)

unsafeThawIOCArray :: Ix i => CArray i e -> IO (IOCArray i e)

zeroElem :: Storable a => a -> a

Hackish way to get the zero element for a Storable type.

unsafeArrayCArray :: (Storable e, Ix i) => (i, i) -> [(Int, e)] -> e -> IO (CArray i e)

unsafeReplaceCArray :: (Storable e, Ix i) => CArray i e -> [(Int, e)] -> IO (CArray i e)

unsafeAccumCArray :: (Storable e, Ix i) => (e -> e' -> e) -> CArray i e -> [(Int, e')] -> IO (CArray i e)

unsafeAccumArrayCArray :: (Storable e, Ix i) => (e -> e' -> e) -> e -> (i, i) -> [(Int, e')] -> IO (CArray i e)

eqCArray :: (Storable e, Ix i, Eq e) => CArray i e -> CArray i e -> Bool

cmpCArray :: (Storable e, Ix i, Ord e) => CArray i e -> CArray i e -> Ordering

cmpIntCArray :: (Storable e, Ord e) => CArray Int e -> CArray Int e -> Ordering

reshape :: (Ix i, Ix j) => (j, j) -> CArray i e -> CArray j e

O(1) reshape an array. The number of elements in the new shape must not exceed the number in the old shape. The elements are in C-style ordering.

flatten :: Ix i => CArray i e -> CArray Int e

O(1) make a rank 1 array from an arbitrary shape. It has the property that 'reshape (0, size a - 1) a == flatten a'.

ixmapWithIndP :: (Ix i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i' -> i) -> (i -> e -> i' -> e') -> a i e -> a' i' e'

Generic slice and map. This takes the new range, the inverse map on indices, and function to produce the next element. It is the most general operation in its class.

ixmapWithInd :: (Ix i, Ix i', IArray a e, IArray a e') => (i', i') -> (i' -> i) -> (i -> e -> i' -> e') -> a i e -> a i' e'

Less polymorphic version.

ixmapWithP :: (Ix i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i' -> i) -> (e -> e') -> a i e -> a' i' e'

Perform an operation on the elements, independent of their location.

ixmapWith :: (Ix i, Ix i', IArray a e, IArray a e') => (i', i') -> (i' -> i) -> (e -> e') -> a i e -> a i' e'

Less polymorphic version.

ixmapP :: (Ix i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i' -> i) -> a i e -> a' i' e

More polymorphic version of ixmap.

sliceStrideWithP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i, i, i) -> (e -> e') -> a i e -> a' i' e'

More friendly sub-arrays with element mapping.

sliceStrideWith :: (Ix i, Shapable i, Ix i', IArray a e, IArray a e') => (i', i') -> (i, i, i) -> (e -> e') -> a i e -> a i' e'

Less polymorphic version.

sliceStrideP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i, i, i) -> a i e -> a' i' e

Strided sub-array without element mapping.

sliceStride :: (Ix i, Shapable i, Ix i', IArray a e) => (i', i') -> (i, i, i) -> a i e -> a i' e

Less polymorphic version.

sliceWithP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i, i) -> (e -> e') -> a i e -> a' i' e'

Contiguous sub-array with element mapping.

sliceWith :: (Ix i, Shapable i, Ix i', IArray a e, IArray a e') => (i', i') -> (i, i) -> (e -> e') -> a i e -> a i' e'

Less polymorphic version.

sliceP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i, i) -> a i e -> a' i' e

Contiguous sub-array without element mapping.

slice :: (Ix i, Shapable i, Ix i', IArray a e) => (i', i') -> (i, i) -> a i e -> a i' e

Less polymorphic version.

mapCArrayInPlace :: (Ix i, Storable e) => (e -> e) -> CArray i e -> CArray i e

In-place map on CArray. Note that this is IN PLACE so you should not retain any reference to the original. It flagrantly breaks referential transparency!

indexes :: (Ix i, Shapable i, IArray a e) => a i e -> i -> [Int]

offsetShapeFromThenTo :: [Int] -> [Int] -> [Int] -> [Int] -> [Int]

offsetShapeFromTo :: [Int] -> [Int] -> [Int] -> [Int]

offsetShapeFromTo' :: ([[Int]] -> [[Int]]) -> [Int] -> [Int] -> [Int] -> [Int]

offsets :: (Ix a, Shapable a) => (a, a) -> a -> [Int]

normp :: (Ix i, RealFloat e', Abs e e', IArray a e) => e' -> a i e -> e'

p-norm on the array taken as a vector

norm2 :: (Ix i, Floating e', Abs e e', IArray a e) => a i e -> e'

2-norm on the array taken as a vector (Frobenius norm for matrices)

normSup :: (Ix i, Num e', Ord e', Abs e e', IArray a e) => a i e -> e'

Sup norm on the array taken as a vector

liftArrayP :: (Ix i, IArray a e, IArray a1 e1) => (e -> e1) -> a i e -> a1 i e1

Polymorphic version of amap.

liftArray :: (Ix i, IArray a e, IArray a e1) => (e -> e1) -> a i e -> a i e1

Equivalent to amap. Here for consistency only.

liftArray2P :: (Ix i, IArray a e, IArray a1 e1, IArray a2 e2) => (e -> e1 -> e2) -> a i e -> a1 i e1 -> a2 i e2

Polymorphic 2-array lift.

liftArray2 :: (Ix i, IArray a e, IArray a e1, IArray a e2) => (e -> e1 -> e2) -> a i e -> a i e1 -> a i e2

Less polymorphic version.

liftArray3P :: (Ix i, IArray a e, IArray a1 e1, IArray a2 e2, IArray a3 e3) => (e -> e1 -> e2 -> e3) -> a i e -> a1 i e1 -> a2 i e2 -> a3 i e3

Polymorphic 3-array lift.

liftArray3 :: (Ix i, IArray a e, IArray a e1, IArray a e2, IArray a e3) => (e -> e1 -> e2 -> e3) -> a i e -> a i e1 -> a i e2 -> a i e3

Less polymorphic version.

class Abs a b | a -> b where

Hack so that norms have a sensible type.

Methods

abs_ :: a -> b

Instances

Abs Double Double

Abs Float Float

Abs (Complex Double) Double

Abs (Complex Float) Float

mallocForeignPtrArrayAligned :: Storable a => Int -> IO (ForeignPtr a)

Allocate an array which is 16-byte aligned. Essential for SIMD instructions.

mallocForeignPtrBytesAligned :: Int -> IO (ForeignPtr a)

Allocate memory which is 16-byte aligned. This is essential for SIMD instructions. We know that mallocPlainForeignPtrBytes will give word-aligned memory, so we pad enough to be able to return the desired amount of memory after aligning our pointer.

createCArray :: (Ix i, Storable e) => (i, i) -> (Ptr e -> IO ()) -> IO (CArray i e)

Make a new CArray with an IO action.

unsafeCreateCArray :: (Ix i, Storable e) => (i, i) -> (Ptr e -> IO ()) -> CArray i e