Storable-based vectors

Mutable Storable-based vectors

The member functions of this class facilitate writing values of primitive types to raw memory (which may have been allocated with the above mentioned routines) and reading values from blocks of raw memory. The class, furthermore, includes support for computing the storage requirements and alignment restrictions of storable types.

Memory addresses are represented as values of type Ptr a, for some a which is an instance of class Storable. The type argument to Ptr helps provide some valuable type safety in FFI code (you can't mix pointers of different types without an explicit cast), while helping the Haskell type system figure out which marshalling method is needed for a given pointer.

All marshalling between Haskell and a foreign language ultimately boils down to translating Haskell data structures into the binary representation of a corresponding data structure of the foreign language and vice versa. To code this marshalling in Haskell, it is necessary to manipulate primitive data types stored in unstructured memory blocks. The class Storable facilitates this manipulation on all types for which it is instantiated, which are the standard basic types of Haskell, the fixed size Int types (Int8, Int16, Int32, Int64), the fixed size Word types (Word8, Word16, Word32, Word64), StablePtr, all types from Foreign.C.Types, as well as Ptr.

Minimal complete definition: sizeOf, alignment, one of peek, peekElemOff and peekByteOff, and one of poke, pokeElemOff and pokeByteOff.

Empty vector

Vector with exaclty one element

Prepend an element

Append an element

Vector of the given length with the given value in each position

Generate a vector of the given length by applying the function to each index

Concatenate two vectors

Create a copy of a vector. Useful when dealing with slices.

Indexing

First element

Last element

Monadic indexing which can be strict in the vector while remaining lazy in the element

Unsafe indexing without bounds checking

Yield the first element of a vector without checking if the vector is empty

Yield the last element of a vector without checking if the vector is empty

Unsafe monadic indexing without bounds checks

Yield a part of the vector without copying it. Safer version of basicUnsafeSlice.

Yield all but the last element without copying.

All but the first element (without copying).

Yield the first n elements without copying.

Yield all but the first n elements without copying.

Unsafely yield a part of the vector without copying it and without performing bounds checks.

Map a function over a vector

Apply a function to every index/value pair

Zip two vectors with the given function.

Zip three vectors with the given function.

Zip two vectors and their indices with the given function.

Zip three vectors and their indices with the given function.

Drop elements which do not satisfy the predicate

Drop elements that do not satisfy the predicate (applied to values and their indices)

Yield the longest prefix of elements satisfying the predicate.

Drop the longest prefix of elements that satisfy the predicate.

Split the vector in two parts, the first one containing those elements that satisfy the predicate and the second one those that don't. The relative order of the elements is preserved at the cost of a (sometimes) reduced performance compared to unstablePartition.

Split the vector in two parts, the first one containing those elements that satisfy the predicate and the second one those that don't. The order of the elements is not preserved.

Split the vector into the longest prefix of elements that satisfy the predicate and the rest.

Split the vector into the longest prefix of elements that do not satisfy the predicate and the rest.

Check whether the vector contains an element

Inverse of elem

Yield Just the first element matching the predicate or Nothing if no such element exists.

Yield Just the index of the first element matching the predicate or Nothing if no such element exists.

Yield the indices of elements satisfying the predicate

Yield Just the index of the first occurence of the given element or Nothing if the vector does not contain the element

Yield the indices of all occurences of the given element

Left fold

Lefgt fold on non-empty vectors

Left fold with strict accumulator

Left fold on non-empty vectors with strict accumulator

Right fold

Right fold on non-empty vectors

Right fold with a strict accumulator

Right fold on non-empty vectors with strict accumulator

Left fold (function applied to each element and its index)

Left fold with strict accumulator (function applied to each element and its index)

Right fold (function applied to each element and its index)

Right fold with strict accumulator (function applied to each element and its index)

The unfoldr function is a `dual' to foldr: while foldr reduces a vector to a summary value, unfoldr builds a list from a seed value. The function takes the element and returns Nothing if it is done generating the vector or returns Just (a,b), in which case, a is a prepended to the vector and b is used as the next element in a recursive call.

A simple use of unfoldr:

 unfoldr (\b -> if b == 0 then Nothing else Just (b, b-1)) 10
  [10,9,8,7,6,5,4,3,2,1]

Unfold at most n elements

Prefix scan

Prefix scan with strict accumulator

Suffix scan

Suffix scan with strict accumulator

Haskell-style scan

Haskell-style scan with strict accumulator

Scan over a non-empty Vector

Scan over a non-empty Vector with a strict accumulator

Prefix right-to-left scan

Prefix right-to-left scan with strict accumulator

Suffix right-to-left scan

Suffix right-to-left scan with strict accumulator

Haskell-style right-to-left scan

Haskell-style right-to-left scan with strict accumulator

Right-to-left scan over a non-empty vector

Right-to-left scan over a non-empty vector with a strict accumulator

Yield a vector of the given length containing the values x, x+1 etc. This operation is usually more efficient than enumFromTo.

Yield a vector of the given length containing the values x, x+y, x+y+y etc. This operations is usually more efficient than enumFromThenTo.

Enumerate values from x to y.

WARNING: This operation can be very inefficient. If at all possible, use enumFromN instead.

Enumerate values from x to y with a specific step z.

WARNING: This operation can be very inefficient. If at all possible, use enumFromStepN instead.

Convert a vector to a list

Convert a list to a vector

Convert the first n elements of a list to a vector

 fromListN n xs = fromList (take n xs)

Perform the monadic action the given number of times and store the results in a vector.

Apply the monadic action to all elements of the vector, yielding a vector of results

Apply the monadic action to all elements of a vector and ignore the results

Apply the monadic action to all elements of the vector, yielding a vector of results

Apply the monadic action to all elements of a vector and ignore the results

Zip the two vectors with the monadic action and yield a vector of results

Zip the two vectors with the monadic action and ignore the results

Drop elements that do not satisfy the monadic predicate

Monadic fold

Monadic fold with strict accumulator

Monadic fold over non-empty vectors

Monad fold over non-empty vectors with strict accumulator

Destructively initialise a vector.

Apply a destructive operation to a vector. The operation is applied to a copy of the vector unless it can be safely performed in place.

Copy an immutable vector into a mutable one. The two vectors must have the same length.

Copy an immutable vector into a mutable one. The two vectors must have the same length. This is not checked.

Create a vector from a ForeignPtr with an offset and a length. The data may not be modified through the ForeignPtr afterwards.

Yield the underlying ForeignPtr together with the offset to the data and its length. The data may not be modified through the ForeignPtr.

Pass a pointer to the vector's data to the IO action. The data may not be modified through the 'Ptr.