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