primitive-0.5.0.1: Primitive memory-related operations

Portability | non-portable
Maintainer | Roman Leshchinskiy <rl@cse.unsw.edu.au>
Safe Haskell | None

Data.Primitive.Array

Description

Primitive boxed arrays

Synopsis

- data Array a = Array (Array# a)
- data MutableArray s a = MutableArray (MutableArray# s a)
- newArray :: PrimMonad m => Int -> a -> m (MutableArray (PrimState m) a)
- readArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> m a
- writeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> a -> m ()
- indexArray :: Array a -> Int -> a
- indexArrayM :: Monad m => Array a -> Int -> m a
- unsafeFreezeArray :: PrimMonad m => MutableArray (PrimState m) a -> m (Array a)
- unsafeThawArray :: PrimMonad m => Array a -> m (MutableArray (PrimState m) a)
- sameMutableArray :: MutableArray s a -> MutableArray s a -> Bool
- copyArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Array a -> Int -> Int -> m ()
- copyMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> MutableArray (PrimState m) a -> Int -> Int -> m ()

# Documentation

data Array a Source

Boxed arrays

Constructors

Array (Array# a) |

Instances

Typeable1 Array |
Typeable a => Data (Array a) |

data MutableArray s a Source

Mutable boxed arrays associated with a primitive state token.

Constructors

MutableArray (MutableArray# s a) |

Instances

Typeable2 MutableArray |
(Typeable s, Typeable a) => Data (MutableArray s a) |

newArray :: PrimMonad m => Int -> a -> m (MutableArray (PrimState m) a)Source

Create a new mutable array of the specified size and initialise all elements with the given value.

readArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> m aSource

Read a value from the array at the given index.

writeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> a -> m ()Source

Write a value to the array at the given index.

indexArray :: Array a -> Int -> aSource

Read a value from the immutable array at the given index.

indexArrayM :: Monad m => Array a -> Int -> m aSource

Monadically read a value from the immutable array at the given index. This allows us to be strict in the array while remaining lazy in the read element which is very useful for collective operations. Suppose we want to copy an array. We could do something like this:

     copy marr arr ... = do ...
                            writeArray marr i (indexArray arr i) ...
                            ...

But since primitive arrays are lazy, the calls to `indexArray` will not be evaluated. Rather, `marr` will be filled with thunks each of which would retain a reference to `arr`. This is definitely not what we want!

With `indexArrayM`, we can instead write

     copy marr arr ... = do ...
                            x <- indexArrayM arr i
                            writeArray marr i x
                            ...

Now, indexing is executed immediately although the returned element is still not evaluated.

unsafeFreezeArray :: PrimMonad m => MutableArray (PrimState m) a -> m (Array a)Source

Convert a mutable array to an immutable one without copying. The array should not be modified after the conversion.

unsafeThawArray :: PrimMonad m => Array a -> m (MutableArray (PrimState m) a)Source

Convert an immutable array to an mutable one without copying. The immutable array should not be used after the conversion.

sameMutableArray :: MutableArray s a -> MutableArray s a -> Bool Source

Check whether the two arrays refer to the same memory block.

copyArray Source

Arguments

:: PrimMonad m |
=> MutableArray (PrimState m) a | destination array
-> Int | offset into destination array
-> Array a | source array
-> Int | offset into source array
-> Int | number of elements to copy
-> m () |

Copy a slice of an immutable array to a mutable array.

copyMutableArray Source

Arguments

:: PrimMonad m |
=> MutableArray (PrimState m) a | destination array
-> Int | offset into destination array
-> MutableArray (PrimState m) a | source array
-> Int | offset into source array
-> Int | number of elements to copy
-> m () |

Copy a slice of a mutable array to another array. The two arrays may not be the same.