1{-# LANGUAGE CPP #-} 2 3-- | 4-- Module : Data.Vector.Unboxed.Mutable 5-- Copyright : (c) Roman Leshchinskiy 2009-2010 6-- License : BSD-style 7-- 8-- Maintainer : Roman Leshchinskiy <rl@cse.unsw.edu.au> 9-- Stability : experimental 10-- Portability : non-portable 11-- 12-- Mutable adaptive unboxed vectors 13-- 14 15module Data.Vector.Unboxed.Mutable ( 16 -- * Mutable vectors of primitive types 17 MVector(..), IOVector, STVector, Unbox, 18 19 -- * Accessors 20 21 -- ** Length information 22 length, null, 23 24 -- ** Extracting subvectors 25 slice, init, tail, take, drop, splitAt, 26 unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop, 27 28 -- ** Overlapping 29 overlaps, 30 31 -- * Construction 32 33 -- ** Initialisation 34 new, unsafeNew, replicate, replicateM, clone, 35 36 -- ** Growing 37 grow, unsafeGrow, 38 39 -- ** Restricting memory usage 40 clear, 41 42 -- * Zipping and unzipping 43 zip, zip3, zip4, zip5, zip6, 44 unzip, unzip3, unzip4, unzip5, unzip6, 45 46 -- * Accessing individual elements 47 read, write, modify, swap, 48 unsafeRead, unsafeWrite, unsafeModify, unsafeSwap, 49 50 -- * Modifying vectors 51 nextPermutation, 52 53 -- ** Filling and copying 54 set, copy, move, unsafeCopy, unsafeMove 55) where 56 57import Data.Vector.Unboxed.Base 58import qualified Data.Vector.Generic.Mutable as G 59import Data.Vector.Fusion.Util ( delayed_min ) 60import Control.Monad.Primitive 61 62import Prelude hiding ( length, null, replicate, reverse, map, read, 63 take, drop, splitAt, init, tail, 64 zip, zip3, unzip, unzip3 ) 65 66-- don't import an unused Data.Vector.Internal.Check 67#define NOT_VECTOR_MODULE 68#include "vector.h" 69 70-- Length information 71-- ------------------ 72 73-- | Length of the mutable vector. 74length :: Unbox a => MVector s a -> Int 75{-# INLINE length #-} 76length = G.length 77 78-- | Check whether the vector is empty 79null :: Unbox a => MVector s a -> Bool 80{-# INLINE null #-} 81null = G.null 82 83-- Extracting subvectors 84-- --------------------- 85 86-- | Yield a part of the mutable vector without copying it. The vector must 87-- contain at least @i+n@ elements. 88slice :: Unbox a 89 => Int -- ^ @i@ starting index 90 -> Int -- ^ @n@ length 91 -> MVector s a 92 -> MVector s a 93{-# INLINE slice #-} 94slice = G.slice 95 96take :: Unbox a => Int -> MVector s a -> MVector s a 97{-# INLINE take #-} 98take = G.take 99 100drop :: Unbox a => Int -> MVector s a -> MVector s a 101{-# INLINE drop #-} 102drop = G.drop 103 104splitAt :: Unbox a => Int -> MVector s a -> (MVector s a, MVector s a) 105{-# INLINE splitAt #-} 106splitAt = G.splitAt 107 108init :: Unbox a => MVector s a -> MVector s a 109{-# INLINE init #-} 110init = G.init 111 112tail :: Unbox a => MVector s a -> MVector s a 113{-# INLINE tail #-} 114tail = G.tail 115 116-- | Yield a part of the mutable vector without copying it. No bounds checks 117-- are performed. 118unsafeSlice :: Unbox a 119 => Int -- ^ starting index 120 -> Int -- ^ length of the slice 121 -> MVector s a 122 -> MVector s a 123{-# INLINE unsafeSlice #-} 124unsafeSlice = G.unsafeSlice 125 126unsafeTake :: Unbox a => Int -> MVector s a -> MVector s a 127{-# INLINE unsafeTake #-} 128unsafeTake = G.unsafeTake 129 130unsafeDrop :: Unbox a => Int -> MVector s a -> MVector s a 131{-# INLINE unsafeDrop #-} 132unsafeDrop = G.unsafeDrop 133 134unsafeInit :: Unbox a => MVector s a -> MVector s a 135{-# INLINE unsafeInit #-} 136unsafeInit = G.unsafeInit 137 138unsafeTail :: Unbox a => MVector s a -> MVector s a 139{-# INLINE unsafeTail #-} 140unsafeTail = G.unsafeTail 141 142-- Overlapping 143-- ----------- 144 145-- | Check whether two vectors overlap. 146overlaps :: Unbox a => MVector s a -> MVector s a -> Bool 147{-# INLINE overlaps #-} 148overlaps = G.overlaps 149 150-- Initialisation 151-- -------------- 152 153-- | Create a mutable vector of the given length. 154new :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a) 155{-# INLINE new #-} 156new = G.new 157 158-- | Create a mutable vector of the given length. The memory is not initialized. 159unsafeNew :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a) 160{-# INLINE unsafeNew #-} 161unsafeNew = G.unsafeNew 162 163-- | Create a mutable vector of the given length (0 if the length is negative) 164-- and fill it with an initial value. 165replicate :: (PrimMonad m, Unbox a) => Int -> a -> m (MVector (PrimState m) a) 166{-# INLINE replicate #-} 167replicate = G.replicate 168 169-- | Create a mutable vector of the given length (0 if the length is negative) 170-- and fill it with values produced by repeatedly executing the monadic action. 171replicateM :: (PrimMonad m, Unbox a) => Int -> m a -> m (MVector (PrimState m) a) 172{-# INLINE replicateM #-} 173replicateM = G.replicateM 174 175-- | Create a copy of a mutable vector. 176clone :: (PrimMonad m, Unbox a) 177 => MVector (PrimState m) a -> m (MVector (PrimState m) a) 178{-# INLINE clone #-} 179clone = G.clone 180 181-- Growing 182-- ------- 183 184-- | Grow a vector by the given number of elements. The number must be 185-- positive. 186grow :: (PrimMonad m, Unbox a) 187 => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a) 188{-# INLINE grow #-} 189grow = G.grow 190 191-- | Grow a vector by the given number of elements. The number must be 192-- positive but this is not checked. 193unsafeGrow :: (PrimMonad m, Unbox a) 194 => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a) 195{-# INLINE unsafeGrow #-} 196unsafeGrow = G.unsafeGrow 197 198-- Restricting memory usage 199-- ------------------------ 200 201-- | Reset all elements of the vector to some undefined value, clearing all 202-- references to external objects. This is usually a noop for unboxed vectors. 203clear :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> m () 204{-# INLINE clear #-} 205clear = G.clear 206 207-- Accessing individual elements 208-- ----------------------------- 209 210-- | Yield the element at the given position. 211read :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a 212{-# INLINE read #-} 213read = G.read 214 215-- | Replace the element at the given position. 216write :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> a -> m () 217{-# INLINE write #-} 218write = G.write 219 220-- | Modify the element at the given position. 221modify :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> (a -> a) -> Int -> m () 222{-# INLINE modify #-} 223modify = G.modify 224 225-- | Swap the elements at the given positions. 226swap :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m () 227{-# INLINE swap #-} 228swap = G.swap 229 230 231-- | Yield the element at the given position. No bounds checks are performed. 232unsafeRead :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a 233{-# INLINE unsafeRead #-} 234unsafeRead = G.unsafeRead 235 236-- | Replace the element at the given position. No bounds checks are performed. 237unsafeWrite 238 :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> a -> m () 239{-# INLINE unsafeWrite #-} 240unsafeWrite = G.unsafeWrite 241 242-- | Modify the element at the given position. No bounds checks are performed. 243unsafeModify :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> (a -> a) -> Int -> m () 244{-# INLINE unsafeModify #-} 245unsafeModify = G.unsafeModify 246 247-- | Swap the elements at the given positions. No bounds checks are performed. 248unsafeSwap 249 :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m () 250{-# INLINE unsafeSwap #-} 251unsafeSwap = G.unsafeSwap 252 253-- Filling and copying 254-- ------------------- 255 256-- | Set all elements of the vector to the given value. 257set :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> a -> m () 258{-# INLINE set #-} 259set = G.set 260 261-- | Copy a vector. The two vectors must have the same length and may not 262-- overlap. 263copy :: (PrimMonad m, Unbox a) 264 => MVector (PrimState m) a -- ^ target 265 -> MVector (PrimState m) a -- ^ source 266 -> m () 267{-# INLINE copy #-} 268copy = G.copy 269 270-- | Copy a vector. The two vectors must have the same length and may not 271-- overlap. This is not checked. 272unsafeCopy :: (PrimMonad m, Unbox a) 273 => MVector (PrimState m) a -- ^ target 274 -> MVector (PrimState m) a -- ^ source 275 -> m () 276{-# INLINE unsafeCopy #-} 277unsafeCopy = G.unsafeCopy 278 279-- | Move the contents of a vector. The two vectors must have the same 280-- length. 281-- 282-- If the vectors do not overlap, then this is equivalent to 'copy'. 283-- Otherwise, the copying is performed as if the source vector were 284-- copied to a temporary vector and then the temporary vector was copied 285-- to the target vector. 286move :: (PrimMonad m, Unbox a) 287 => MVector (PrimState m) a -- ^ target 288 -> MVector (PrimState m) a -- ^ source 289 -> m () 290{-# INLINE move #-} 291move = G.move 292 293-- | Move the contents of a vector. The two vectors must have the same 294-- length, but this is not checked. 295-- 296-- If the vectors do not overlap, then this is equivalent to 'unsafeCopy'. 297-- Otherwise, the copying is performed as if the source vector were 298-- copied to a temporary vector and then the temporary vector was copied 299-- to the target vector. 300unsafeMove :: (PrimMonad m, Unbox a) 301 => MVector (PrimState m) a -- ^ target 302 -> MVector (PrimState m) a -- ^ source 303 -> m () 304{-# INLINE unsafeMove #-} 305unsafeMove = G.unsafeMove 306 307-- | Compute the next (lexicographically) permutation of given vector in-place. 308-- Returns False when input is the last permutation 309nextPermutation :: (PrimMonad m,Ord e,Unbox e) => MVector (PrimState m) e -> m Bool 310{-# INLINE nextPermutation #-} 311nextPermutation = G.nextPermutation 312 313#define DEFINE_MUTABLE 314#include "unbox-tuple-instances" 315