Copyright	(c) 2008 Jed Brown
License	BSD-style
Maintainer	jed@59A2.org
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell98

Data.Array.CArray

Contents

CArray type
Multi-dimensional
- Fast reshaping
- Query
Mapping
- General
- Slicing
Lifting
Norms
Types
Unsafe low-level
The overloaded immutable array interface

Description

This module provides the immutable CArray which uses 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.

CArray has an instance of Binary.

Synopsis

CArray type

data CArray i e Source #

The immutable array type.

Instances

Storable e => IArray CArray e Source #
Methods bounds :: Ix i => CArray i e -> (i, i) # numElements :: Ix i => CArray i e -> Int unsafeArray :: Ix i => (i, i) -> [(Int, e)] -> CArray i e unsafeAt :: Ix i => CArray i e -> Int -> e unsafeReplace :: Ix i => CArray i e -> [(Int, e)] -> CArray i e unsafeAccum :: Ix i => (e -> e' -> e) -> CArray i e -> [(Int, e')] -> CArray i e unsafeAccumArray :: Ix i => (e -> e' -> e) -> e -> (i, i) -> [(Int, e')] -> CArray i e
(Ix ix, Eq e, Storable e) => Eq (CArray ix e) Source #
Methods (==) :: CArray ix e -> CArray ix e -> Bool # (/=) :: CArray ix e -> CArray ix e -> Bool #
(Data e, Data i) => Data (CArray i e) Source #
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> CArray i e -> c (CArray i e) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (CArray i e) # toConstr :: CArray i e -> Constr # dataTypeOf :: CArray i e -> DataType # dataCast1 :: Typeable (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c (CArray i e)) # dataCast2 :: Typeable ( -> * -> *) t => (forall d a. (Data d, Data a) => c (t d a)) -> Maybe (c (CArray i e)) # gmapT :: (forall b. Data b => b -> b) -> CArray i e -> CArray i e # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> CArray i e -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> CArray i e -> r # gmapQ :: (forall d. Data d => d -> u) -> CArray i e -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> CArray i e -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> CArray i e -> m (CArray i e) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> CArray i e -> m (CArray i e) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> CArray i e -> m (CArray i e) #
(Ix ix, Ord e, Storable e) => Ord (CArray ix e) Source #
Methods compare :: CArray ix e -> CArray ix e -> Ordering # (<) :: CArray ix e -> CArray ix e -> Bool # (<=) :: CArray ix e -> CArray ix e -> Bool # (>) :: CArray ix e -> CArray ix e -> Bool # (>=) :: CArray ix e -> CArray ix e -> Bool # max :: CArray ix e -> CArray ix e -> CArray ix e # min :: CArray ix e -> CArray ix e -> CArray ix e #
(Ix ix, Show ix, Show e, Storable e) => Show (CArray ix e) Source #
Methods showsPrec :: Int -> CArray ix e -> ShowS # show :: CArray ix e -> String # showList :: [CArray ix e] -> ShowS #
(Ix i, Arbitrary i, Storable e, Arbitrary e) => Arbitrary (CArray i e) Source #
Methods arbitrary :: Gen (CArray i e) # shrink :: CArray i e -> [CArray i e] #
(Ix i, CoArbitrary i, Storable e, CoArbitrary e) => CoArbitrary (CArray i e) Source #
Methods coarbitrary :: CArray i e -> Gen b -> Gen b #
(Ix i, Binary i, Binary e, Storable e) => Binary (CArray i e) Source #
Methods put :: CArray i e -> Put # get :: Get (CArray i e) # putList :: [CArray i e] -> Put #

Multi-dimensional

Fast reshaping

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

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 Source #

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

Query

rank :: (Shapable i, Ix i, IArray a e) => a i e -> Int #

Determine the rank of an array.

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

Canonical representation of the shape. The following properties hold: 'length . shape = rank' 'product . shape = size'

size :: (Ix i, IArray a e) => a i e -> Int #

Number of elements in the Array.

Mapping

General

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' Source #

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' Source #

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' Source #

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' Source #

Less polymorphic version.

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

More polymorphic version of ixmap.

Slicing

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' Source #

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' Source #

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 Source #

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 Source #

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' Source #

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' Source #

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 Source #

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 Source #

Less polymorphic version.

Lifting

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

Polymorphic version of amap.

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

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 Source #

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 Source #

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 Source #

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 Source #

Less polymorphic version.

Norms

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

p-norm on the array taken as a vector

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

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' Source #

Sup norm on the array taken as a vector

Types

class Shapable i #

We need this type class to distinguish between different tuples of Ix. There are Shapable instances for homogenous Int tuples, but may Haddock doesn't see them.

Minimal complete definition

sRank, sShape, sBounds

Instances

Shapable Int
Methods sRank :: Int -> Int # sShape :: Int -> Int -> [Int] # sBounds :: [Int] -> (Int, Int) #
Shapable (Int, Int)
Methods sRank :: (Int, Int) -> Int # sShape :: (Int, Int) -> (Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int), (Int, Int)) #
Shapable (Int, Int, Int)
Methods sRank :: (Int, Int, Int) -> Int # sShape :: (Int, Int, Int) -> (Int, Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int, Int), (Int, Int, Int)) #
Shapable (Int, Int, Int, Int)
Methods sRank :: (Int, Int, Int, Int) -> Int # sShape :: (Int, Int, Int, Int) -> (Int, Int, Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int, Int, Int), (Int, Int, Int, Int)) #
Shapable (Int, Int, Int, Int, Int)
Methods sRank :: (Int, Int, Int, Int, Int) -> Int # sShape :: (Int, Int, Int, Int, Int) -> (Int, Int, Int, Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int, Int, Int, Int), (Int, Int, Int, Int, Int)) #
Shapable (Int, Int, Int, Int, Int, Int)
Methods sRank :: (Int, Int, Int, Int, Int, Int) -> Int # sShape :: (Int, Int, Int, Int, Int, Int) -> (Int, Int, Int, Int, Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int, Int, Int, Int, Int), (Int, Int, Int, Int, Int, Int)) #
Shapable (Int, Int, Int, Int, Int, Int, Int)
Methods sRank :: (Int, Int, Int, Int, Int, Int, Int) -> Int # sShape :: (Int, Int, Int, Int, Int, Int, Int) -> (Int, Int, Int, Int, Int, Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int, Int, Int, Int, Int, Int), (Int, Int, Int, Int, Int, Int, Int)) #
Shapable (Int, Int, Int, Int, Int, Int, Int, Int)
Methods sRank :: (Int, Int, Int, Int, Int, Int, Int, Int) -> Int # sShape :: (Int, Int, Int, Int, Int, Int, Int, Int) -> (Int, Int, Int, Int, Int, Int, Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int, Int, Int, Int, Int, Int, Int), (Int, Int, Int, Int, Int, Int, Int, Int)) #
Shapable (Int, Int, Int, Int, Int, Int, Int, Int, Int)
Methods sRank :: (Int, Int, Int, Int, Int, Int, Int, Int, Int) -> Int # sShape :: (Int, Int, Int, Int, Int, Int, Int, Int, Int) -> (Int, Int, Int, Int, Int, Int, Int, Int, Int) -> [Int] # sBounds :: [Int] -> ((Int, Int, Int, Int, Int, Int, Int, Int, Int), (Int, Int, Int, Int, Int, Int, Int, Int, Int)) #

class Abs a b | a -> b Source #

Hack so that norms have a sensible type.

Minimal complete definition

abs_

Instances

Abs Double Double Source #
Methods abs_ :: Double -> Double Source #
Abs Float Float Source #
Methods abs_ :: Float -> Float Source #
Abs (Complex Double) Double Source #
Methods abs_ :: Complex Double -> Double Source #
Abs (Complex Float) Float Source #
Methods abs_ :: Complex Float -> Float Source #

Unsafe low-level

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

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.

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

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) Source #

O(1) Extract ForeignPtr from a CArray.

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

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) Source #

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

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

Make a new CArray with an IO action.

The overloaded immutable array interface

module Data.Array.IArray