Safe Haskell | None |
---|---|

Language | Haskell2010 |

Generic `Vector`

interface unsafe functions. These perform no bounds
checking, and may cause segmentation faults etc.! Import as:

import qualified RIO.Vector.Unsafe as V'

## Synopsis

- class MVector (Mutable v) a => Vector (v :: Type -> Type) a where
- basicUnsafeFreeze :: PrimMonad m => Mutable v (PrimState m) a -> m (v a)
- basicUnsafeThaw :: PrimMonad m => v a -> m (Mutable v (PrimState m) a)
- basicLength :: v a -> Int
- basicUnsafeSlice :: Int -> Int -> v a -> v a
- basicUnsafeIndexM :: Monad m => v a -> Int -> m a
- basicUnsafeCopy :: PrimMonad m => Mutable v (PrimState m) a -> v a -> m ()
- elemseq :: v a -> a -> b -> b

- unsafeIndex :: Vector v a => v a -> Int -> a
- unsafeHead :: Vector v a => v a -> a
- unsafeLast :: Vector v a => v a -> a
- unsafeIndexM :: (Vector v a, Monad m) => v a -> Int -> m a
- unsafeHeadM :: (Vector v a, Monad m) => v a -> m a
- unsafeLastM :: (Vector v a, Monad m) => v a -> m a
- unsafeSlice :: Vector v a => Int -> Int -> v a -> v a
- unsafeInit :: Vector v a => v a -> v a
- unsafeTail :: Vector v a => v a -> v a
- unsafeTake :: Vector v a => Int -> v a -> v a
- unsafeDrop :: Vector v a => Int -> v a -> v a
- unsafeUpd :: Vector v a => v a -> [(Int, a)] -> v a
- unsafeUpdate :: (Vector v a, Vector v (Int, a)) => v a -> v (Int, a) -> v a
- unsafeUpdate_ :: (Vector v a, Vector v Int) => v a -> v Int -> v a -> v a
- unsafeAccum :: Vector v a => (a -> b -> a) -> v a -> [(Int, b)] -> v a
- unsafeAccumulate :: (Vector v a, Vector v (Int, b)) => (a -> b -> a) -> v a -> v (Int, b) -> v a
- unsafeAccumulate_ :: (Vector v a, Vector v Int, Vector v b) => (a -> b -> a) -> v a -> v Int -> v b -> v a
- unsafeBackpermute :: (Vector v a, Vector v Int) => v a -> v Int -> v a
- unsafeFreeze :: (PrimMonad m, Vector v a) => Mutable v (PrimState m) a -> m (v a)
- unsafeThaw :: (PrimMonad m, Vector v a) => v a -> m (Mutable v (PrimState m) a)
- unsafeCopy :: (PrimMonad m, Vector v a) => Mutable v (PrimState m) a -> v a -> m ()

# Immutable vectors

class MVector (Mutable v) a => Vector (v :: Type -> Type) a where #

Class of immutable vectors. Every immutable vector is associated with its
mutable version through the `Mutable`

type family. Methods of this class
should not be used directly. Instead, Data.Vector.Generic and other
Data.Vector modules provide safe and fusible wrappers.

Minimum complete implementation:

basicUnsafeFreeze :: PrimMonad m => Mutable v (PrimState m) a -> m (v a) #

*Assumed complexity: O(1)*

Unsafely convert a mutable vector to its immutable version without copying. The mutable vector may not be used after this operation.

basicUnsafeThaw :: PrimMonad m => v a -> m (Mutable v (PrimState m) a) #

*Assumed complexity: O(1)*

Unsafely convert an immutable vector to its mutable version without copying. The immutable vector may not be used after this operation.

basicLength :: v a -> Int #

*Assumed complexity: O(1)*

Yield the length of the vector.

*Assumed complexity: O(1)*

Yield a slice of the vector without copying it. No range checks are performed.

basicUnsafeIndexM :: Monad m => v a -> Int -> m a #

*Assumed complexity: O(1)*

Yield the element at the given position in a monad. No range checks are performed.

The monad allows us to be strict in the vector if we want. Suppose we had

unsafeIndex :: v a -> Int -> a

instead. Now, if we wanted to copy a vector, we'd do something like

copy mv v ... = ... unsafeWrite mv i (unsafeIndex v i) ...

For lazy vectors, the indexing would not be evaluated which means that we would retain a reference to the original vector in each element we write. This is not what we want!

With `basicUnsafeIndexM`

, we can do

copy mv v ... = ... case basicUnsafeIndexM v i of Box x -> unsafeWrite mv i x ...

which does not have this problem because indexing (but not the returned element!) is evaluated immediately.

basicUnsafeCopy :: PrimMonad m => Mutable v (PrimState m) a -> v a -> m () #

*Assumed complexity: O(n)*

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

Instances of `Vector`

should redefine this method if they wish to support
an efficient block copy operation.

Default definition: copying basic on `basicUnsafeIndexM`

and
`basicUnsafeWrite`

.

elemseq :: v a -> a -> b -> b #

Evaluate `a`

as far as storing it in a vector would and yield `b`

.
The `v a`

argument only fixes the type and is not touched. The method is
only used for optimisation purposes. Thus, it is safe for instances of
`Vector`

to evaluate `a`

less than it would be when stored in a vector
although this might result in suboptimal code.

elemseq v x y = (singleton x `asTypeOf` v) `seq` y

Default defintion: `a`

is not evaluated at all

#### Instances

# Accessors

## Indexing

unsafeIndex :: Vector v a => v a -> Int -> a #

*O(1)* Unsafe indexing without bounds checking

unsafeHead :: Vector v a => v a -> a #

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

unsafeLast :: Vector v a => v a -> a #

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

## Monadic indexing

unsafeIndexM :: (Vector v a, Monad m) => v a -> Int -> m a #

*O(1)* Indexing in a monad without bounds checks. See `indexM`

for an
explanation of why this is useful.

unsafeHeadM :: (Vector v a, Monad m) => v a -> m a #

*O(1)* First element in a monad without checking for empty vectors.
See `indexM`

for an explanation of why this is useful.

unsafeLastM :: (Vector v a, Monad m) => v a -> m a #

*O(1)* Last element in a monad without checking for empty vectors.
See `indexM`

for an explanation of why this is useful.

## Extracting subvectors

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

elements but this is not checked.

unsafeInit :: Vector v a => v a -> v a #

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

unsafeTail :: Vector v a => v a -> v a #

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

unsafeTake :: Vector v a => Int -> v a -> v a #

*O(1)* Yield the first `n`

elements without copying. The vector must
contain at least `n`

elements but this is not checked.

unsafeDrop :: Vector v a => Int -> v a -> v a #

*O(1)* Yield all but the first `n`

elements without copying. The vector
must contain at least `n`

elements but this is not checked.

# Modifying vectors

## Bulk updates

unsafeUpdate :: (Vector v a, Vector v (Int, a)) => v a -> v (Int, a) -> v a #

Same as `update`

but without bounds checking.

unsafeUpdate_ :: (Vector v a, Vector v Int) => v a -> v Int -> v a -> v a #

Same as `update_`

but without bounds checking.

## Accumulations

unsafeAccum :: Vector v a => (a -> b -> a) -> v a -> [(Int, b)] -> v a #

Same as `accum`

but without bounds checking.

unsafeAccumulate :: (Vector v a, Vector v (Int, b)) => (a -> b -> a) -> v a -> v (Int, b) -> v a #

Same as `accumulate`

but without bounds checking.

unsafeAccumulate_ :: (Vector v a, Vector v Int, Vector v b) => (a -> b -> a) -> v a -> v Int -> v b -> v a #

Same as `accumulate_`

but without bounds checking.

## Permutations

unsafeBackpermute :: (Vector v a, Vector v Int) => v a -> v Int -> v a #

Same as `backpermute`

but without bounds checking.

# Conversions

## Mutable vectors

unsafeFreeze :: (PrimMonad m, Vector v a) => Mutable v (PrimState m) a -> m (v a) #

*O(1)* Unsafe convert a mutable vector to an immutable one without
copying. The mutable vector may not be used after this operation.