Portability | non-portable |
---|---|

Stability | experimental |

Maintainer | Roman Leshchinskiy <rl@cse.unsw.edu.au> |

Mutable vectors based on Storable.

- data MVector s a = MVector !(Ptr a) !Int !(ForeignPtr a)
- type IOVector = MVector RealWorld
- type STVector s = MVector s
- class Storable a
- length :: Storable a => MVector s a -> Int
- overlaps :: Storable a => MVector s a -> MVector s a -> Bool
- slice :: Storable a => Int -> Int -> MVector s a -> MVector s a
- new :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
- newWith :: (PrimMonad m, Storable a) => Int -> a -> m (MVector (PrimState m) a)
- read :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m a
- write :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m ()
- swap :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
- clear :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> m ()
- set :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> a -> m ()
- copy :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
- grow :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
- unsafeSlice :: Storable a => Int -> Int -> MVector s a -> MVector s a
- unsafeNew :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
- unsafeNewWith :: (PrimMonad m, Storable a) => Int -> a -> m (MVector (PrimState m) a)
- unsafeRead :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m a
- unsafeWrite :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m ()
- unsafeSwap :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
- unsafeCopy :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
- unsafeGrow :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
- unsafeFromForeignPtr :: Storable a => ForeignPtr a -> Int -> Int -> MVector s a
- unsafeToForeignPtr :: Storable a => MVector s a -> (ForeignPtr a, Int, Int)
- unsafeWith :: Storable a => IOVector a -> (Ptr a -> IO b) -> IO b

# Mutable vectors of `Storable`

types

Mutable `Storable`

-based vectors

MVector !(Ptr a) !Int !(ForeignPtr a) |

class Storable a

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

, for some
`Ptr`

a`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`

.

# Operations on mutable vectors

slice :: Storable a => Int -> Int -> MVector s a -> MVector s aSource

Yield a part of the mutable vector without copying it.

new :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)Source

Create a mutable vector of the given length.

newWith :: (PrimMonad m, Storable a) => Int -> a -> m (MVector (PrimState m) a)Source

Create a mutable vector of the given length and fill it with an initial value.

read :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m aSource

Yield the element at the given position.

write :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m ()Source

Replace the element at the given position.

swap :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()Source

Swap the elements at the given positions.

clear :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> m ()Source

Reset all elements of the vector to some undefined value, clearing all references to external objects. This is usually a noop for unboxed vectors.

set :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> a -> m ()Source

Set all elements of the vector to the given value.

copy :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()Source

Copy a vector. The two vectors must have the same length and may not overlap.

grow :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)Source

Grow a vector by the given number of elements. The number must be positive.

# Unsafe operations

Yield a part of the mutable vector without copying it. No bounds checks are performed.

unsafeNew :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)Source

Create a mutable vector of the given length. The length is not checked.

unsafeNewWith :: (PrimMonad m, Storable a) => Int -> a -> m (MVector (PrimState m) a)Source

Create a mutable vector of the given length and fill it with an initial value. The length is not checked.

unsafeRead :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m aSource

Yield the element at the given position. No bounds checks are performed.

unsafeWrite :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m ()Source

Replace the element at the given position. No bounds checks are performed.

unsafeSwap :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()Source

Swap the elements at the given positions. No bounds checks are performed.

:: (PrimMonad m, Storable a) | |

=> MVector (PrimState m) a | target |

-> MVector (PrimState m) a | source |

-> m () |

Copy a vector. The two vectors must have the same length and may not overlap. This is not checked.

unsafeGrow :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)Source

Grow a vector by the given number of elements. The number must be positive but this is not checked.

# Accessing the underlying memory

:: Storable a | |

=> ForeignPtr a | pointer |

-> Int | offset |

-> Int | length |

-> MVector s a |

Create a mutable vector from a `ForeignPtr`

with an offset and a length.
Modifying data through the `ForeignPtr`

afterwards is unsafe if the vector
could have been frozen before the modification.

unsafeToForeignPtr :: Storable a => MVector s a -> (ForeignPtr a, Int, Int)Source

Yield the underlying `ForeignPtr`

together with the offset to the data
and its length. Modifying the data through the `ForeignPtr`

is
unsafe if the vector could have frozen before the modification.