Data.Grid.Storable

Use case:

• You've got a block of data you want to work with in C or C++ or some other foreign language
• It represents a 2D grid
• Before disposing of it, it would be convenient to treat it as a Vector of vectors (perhaps for inspecting contents).
• Also, I just wanted to see what's involved in creating a Vector instance.

The resulting Grid isn't an especially _good_ instance of a Vector -- many operations on the 'top-level' vector are disallowed -- and there's no mutable equivalent, but it seems to work.

Vec-of-vec view of storable

type Grid a = InternalGrid a (Vector a)

A vector-of-vector view of a block foreign contiguous data

plus helpful types

type InternalGrid = Grid

Accessors

Length information

length :: Grid el (v el) -> Int

O(1) Yield the length of the vector

Indexing

(!) :: Grid el (v el) -> Int -> v el

O(1) Indexing

(!?) :: Grid el (v el) -> Int -> Maybe (v el)

O(1) Safe indexing

head :: Grid el (v el) -> v el

O(1) First element

last :: Grid el (v el) -> v el

O(1) Last element

unsafeIndex :: Grid el (v el) -> Int -> v el

O(1) Unsafe indexing without bounds checking

unsafeHead :: Grid el (v el) -> v el

O(1) First element without checking if the vector is empty

unsafeLast :: Grid el (v el) -> v el

O(1) Last element without checking if the vector is empty

Extracting subvectors (slicing)

slice

Arguments

:: Int

i starting index

-> Int

n length

-> Grid el (v el)

-> Grid el (v el)

O(1) Yield a slice of the vector without copying it. The vector must contain at least i+n elements.

init :: Grid el (v el) -> Grid el (v el)

O(1) Yield all but the last element without copying. The vector may not be empty.

tail :: Grid el (v el) -> Grid el (v el)

O(1) Yield all but the first element without copying. The vector may not be empty.

take :: Int -> Grid el (v el) -> Grid el (v el)

O(1) Yield at the first n elements without copying. The vector may contain less than n elements in which case it is returned unchanged.

drop :: Int -> Grid el (v el) -> Grid el (v el)

O(1) Yield all but the first n elements without copying. The vector may contain less than n elements in which case an empty vector is returned.

Construction

Initialisation

fromVector :: Storable el => Int -> Int -> Vector el -> Grid el

Convert a storable Vector into vector-of-vectors view. Does a "thaw" of the original Vector, which results in a full copy, being made, but has the advantage that the source vector can safely be used again after.

width and height must be > 0 or user error thrown.

Destruction

toList :: (Storable a, NFData a) => Grid a -> IO [Vector a]

convert the Grid into a list of (plain, not storable) Vectors.

Permutations

reverse :: [a] -> [a]

reverse xs returns the elements of xs in reverse order. xs must be finite.

Raw pointers

unsafeToForeignPtr0 :: Grid el -> ForeignPtr el

O(1) Yield the underlying ForeignPtr.

You can assume the pointer points directly to the data (no offset).

The data may not be modified through the ForeignPtr.