Data.Vector.SEXP.Mutable

Vectors that can be passed to and from R with no copying at all. These vectors are wrappers over SEXP vectors used by R. Memory for vectors is allocated from the R heap, and in such way that they can be converted to a SEXP by simple pointer arithmetic (see toSEXP).

Like Data.Vector.Storable.Mutable vectors, the vector type in this module adds one extra level of indirection and a small amount of storage overhead for maintainging lengths and slice offsets. If you're keeping a very large number of tiny vectors in memory, you're better off keeping them as SEXPs and calling fromSEXP on-the-fly.

Mutable slices of SEXP vector types

data MVector s ty a

Mutable R vector. Represented in memory with the same header as SEXP nodes. The second type parameter is phantom, reflecting at the type level the tag of the vector when viewed as a SEXP. The tag of the vector and the representation type are related via ElemRep.

Instances

VECTOR V ty a => Literal (MVector V ty a) ty

Methods

mkSEXPIO :: MVector V ty a -> IO (SEXP V ty)

fromSEXP :: SEXP s ty -> MVector V ty a

fromSEXP :: VECTOR s ty a => SEXP s ty -> MVector s ty a

O(1) Create a vector from a SEXP.

toSEXP :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> m (SEXP (Region m) ty)

O(1) in the common case, O(n) for proper slices. Convert a mutable vector to a SEXP. This can be done efficiently, without copy, because vectors in this module always include a SEXP header immediately before the vector data in memory.

release :: s' <= s => MVector s ty a -> MVector s' ty a

unsafeRelease :: MVector s ty a -> MVector s' ty a

Accessors

Length information

length :: VECTOR s ty a => MVector s ty a -> Int

Length of the mutable vector.

null :: VECTOR s ty a => MVector s ty a -> Bool

Check whether the vector is empty.

Construction

Initialisation

new :: forall m ty a. (MonadR m, VECTOR (Region m) ty a) => Int -> m (MVector (Region m) ty a)

Create a mutable vector of the given length.

unsafeNew :: (MonadR m, VECTOR (Region m) ty a) => Int -> m (MVector (Region m) ty a)

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

replicate :: (MonadR m, VECTOR (Region m) ty a) => Int -> a -> m (MVector (Region m) ty a)

Create a mutable vector of the given length (0 if the length is negative) and fill it with an initial value.

replicateM :: (MonadR m, VECTOR (Region m) ty a) => Int -> m a -> m (MVector (Region m) ty a)

Create a mutable vector of the given length (0 if the length is negative) and fill it with values produced by repeatedly executing the monadic action.

clone :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> m (MVector (Region m) ty a)

Create a copy of a mutable vector.

Extracting subvectors

slice :: VECTOR s ty a => Int -> Int -> MVector s ty a -> MVector s ty a

Yield a part of the mutable vector without copying it.

init :: VECTOR s ty a => MVector s ty a -> MVector s ty a

tail :: VECTOR s ty a => MVector s ty a -> MVector s ty a

take :: VECTOR s ty a => Int -> MVector s ty a -> MVector s ty a

drop :: VECTOR s ty a => Int -> MVector s ty a -> MVector s ty a

splitAt :: VECTOR s ty a => Int -> MVector s ty a -> (MVector s ty a, MVector s ty a)

unsafeSlice

Arguments

:: VECTOR s ty a

=> Int

starting index

-> Int

length of the slice

-> MVector s ty a

-> MVector s ty a

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

unsafeInit :: VECTOR s ty a => MVector s ty a -> MVector s ty a

unsafeTail :: VECTOR s ty a => MVector s ty a -> MVector s ty a

unsafeTake :: VECTOR s ty a => Int -> MVector s ty a -> MVector s ty a

unsafeDrop :: VECTOR s ty a => Int -> MVector s ty a -> MVector s ty a

Overlapping

overlaps :: VECTOR s ty a => MVector s ty a -> MVector s ty a -> Bool

Check whether two vectors overlap.

Restricting memory usage

clear :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> m ()

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

Accessing individual elements

read :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> Int -> m a

Yield the element at the given position.

write :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> Int -> a -> m ()

Replace the element at the given position.

swap :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> Int -> Int -> m ()

Swap the elements at the given positions.

unsafeRead :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> Int -> m a

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

unsafeWrite :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> Int -> a -> m ()

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

unsafeSwap :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> Int -> Int -> m ()

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

Modifying vectors

Filling and copying

set :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> a -> m ()

Set all elements of the vector to the given value.

copy :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> MVector (Region m) ty a -> m ()

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

move :: (MonadR m, VECTOR (Region m) ty a) => MVector (Region m) ty a -> MVector (Region m) ty a -> m ()

Move the contents of a vector. The two vectors must have the same length.

If the vectors do not overlap, then this is equivalent to copy. Otherwise, the copying is performed as if the source vector were copied to a temporary vector and then the temporary vector was copied to the target vector.

unsafeCopy

Arguments

:: (MonadR m, VECTOR (Region m) ty a)

=> MVector (Region m) ty a

target

-> MVector (Region m) ty a

source

-> m ()

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

unsafeMove

Arguments

:: (MonadR m, VECTOR (Region m) ty a)

=> MVector (Region m) ty a

target

-> MVector (Region m) ty a

source

-> m ()

Move the contents of a vector. The two vectors must have the same length, but this is not checked.

If the vectors do not overlap, then this is equivalent to unsafeCopy. Otherwise, the copying is performed as if the source vector were copied to a temporary vector and then the temporary vector was copied to the target vector.