Resolve conflict
[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 ) where
53
54 import Data.Vector.Unboxed.Base
55 import qualified Data.Vector.Generic.Mutable as G
56 import Data.Vector.Fusion.Util ( delayed_min )
57 import Control.Monad.Primitive
58
59 import Prelude hiding ( length, null, replicate, reverse, map, read,
60 take, drop, splitAt, init, tail,
61 zip, zip3, unzip, unzip3 )
62
63 #include "vector.h"
64
65 -- Length information
66 -- ------------------
67
68 -- | Length of the mutable vector.
69 length :: Unbox a => MVector s a -> Int
70 {-# INLINE length #-}
71 length = G.length
72
73 -- | Check whether the vector is empty
74 null :: Unbox a => MVector s a -> Bool
75 {-# INLINE null #-}
76 null = G.null
77
78 -- Extracting subvectors
79 -- ---------------------
80
81 -- | Yield a part of the mutable vector without copying it.
82 slice :: Unbox a => Int -> Int -> MVector s a -> MVector s a
83 {-# INLINE slice #-}
84 slice = G.slice
85
86 take :: Unbox a => Int -> MVector s a -> MVector s a
87 {-# INLINE take #-}
88 take = G.take
89
90 drop :: Unbox a => Int -> MVector s a -> MVector s a
91 {-# INLINE drop #-}
92 drop = G.drop
93
94 splitAt :: Unbox a => Int -> MVector s a -> (MVector s a, MVector s a)
95 {-# INLINE splitAt #-}
96 splitAt = G.splitAt
97
98 init :: Unbox a => MVector s a -> MVector s a
99 {-# INLINE init #-}
100 init = G.init
101
102 tail :: Unbox a => MVector s a -> MVector s a
103 {-# INLINE tail #-}
104 tail = G.tail
105
106 -- | Yield a part of the mutable vector without copying it. No bounds checks
107 -- are performed.
108 unsafeSlice :: Unbox a
109 => Int -- ^ starting index
110 -> Int -- ^ length of the slice
111 -> MVector s a
112 -> MVector s a
113 {-# INLINE unsafeSlice #-}
114 unsafeSlice = G.unsafeSlice
115
116 unsafeTake :: Unbox a => Int -> MVector s a -> MVector s a
117 {-# INLINE unsafeTake #-}
118 unsafeTake = G.unsafeTake
119
120 unsafeDrop :: Unbox a => Int -> MVector s a -> MVector s a
121 {-# INLINE unsafeDrop #-}
122 unsafeDrop = G.unsafeDrop
123
124 unsafeInit :: Unbox a => MVector s a -> MVector s a
125 {-# INLINE unsafeInit #-}
126 unsafeInit = G.unsafeInit
127
128 unsafeTail :: Unbox a => MVector s a -> MVector s a
129 {-# INLINE unsafeTail #-}
130 unsafeTail = G.unsafeTail
131
132 -- Overlapping
133 -- -----------
134
135 -- Check whether two vectors overlap.
136 overlaps :: Unbox a => MVector s a -> MVector s a -> Bool
137 {-# INLINE overlaps #-}
138 overlaps = G.overlaps
139
140 -- Initialisation
141 -- --------------
142
143 -- | Create a mutable vector of the given length.
144 new :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a)
145 {-# INLINE new #-}
146 new = G.new
147
148 -- | Create a mutable vector of the given length. The length is not checked.
149 unsafeNew :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a)
150 {-# INLINE unsafeNew #-}
151 unsafeNew = G.unsafeNew
152
153 -- | Create a mutable vector of the given length (0 if the length is negative)
154 -- and fill it with an initial value.
155 replicate :: (PrimMonad m, Unbox a) => Int -> a -> m (MVector (PrimState m) a)
156 {-# INLINE replicate #-}
157 replicate = G.replicate
158
159 -- | Create a mutable vector of the given length (0 if the length is negative)
160 -- and fill it with values produced by repeatedly executing the monadic action.
161 replicateM :: (PrimMonad m, Unbox a) => Int -> m a -> m (MVector (PrimState m) a)
162 {-# INLINE replicateM #-}
163 replicateM = G.replicateM
164
165 -- | Create a copy of a mutable vector.
166 clone :: (PrimMonad m, Unbox a)
167 => MVector (PrimState m) a -> m (MVector (PrimState m) a)
168 {-# INLINE clone #-}
169 clone = G.clone
170
171 -- Growing
172 -- -------
173
174 -- | Grow a vector by the given number of elements. The number must be
175 -- positive.
176 grow :: (PrimMonad m, Unbox a)
177 => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
178 {-# INLINE grow #-}
179 grow = G.grow
180
181 -- | Grow a vector by the given number of elements. The number must be
182 -- positive but this is not checked.
183 unsafeGrow :: (PrimMonad m, Unbox a)
184 => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
185 {-# INLINE unsafeGrow #-}
186 unsafeGrow = G.unsafeGrow
187
188 -- Restricting memory usage
189 -- ------------------------
190
191 -- | Reset all elements of the vector to some undefined value, clearing all
192 -- references to external objects. This is usually a noop for unboxed vectors.
193 clear :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> m ()
194 {-# INLINE clear #-}
195 clear = G.clear
196
197 -- Accessing individual elements
198 -- -----------------------------
199
200 -- | Yield the element at the given position.
201 read :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a
202 {-# INLINE read #-}
203 read = G.read
204
205 -- | Replace the element at the given position.
206 write :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> a -> m ()
207 {-# INLINE write #-}
208 write = G.write
209
210 -- | Swap the elements at the given positions.
211 swap :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m ()
212 {-# INLINE swap #-}
213 swap = G.swap
214
215
216 -- | Yield the element at the given position. No bounds checks are performed.
217 unsafeRead :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a
218 {-# INLINE unsafeRead #-}
219 unsafeRead = G.unsafeRead
220
221 -- | Replace the element at the given position. No bounds checks are performed.
222 unsafeWrite
223 :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> a -> m ()
224 {-# INLINE unsafeWrite #-}
225 unsafeWrite = G.unsafeWrite
226
227 -- | Swap the elements at the given positions. No bounds checks are performed.
228 unsafeSwap
229 :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m ()
230 {-# INLINE unsafeSwap #-}
231 unsafeSwap = G.unsafeSwap
232
233 -- Filling and copying
234 -- -------------------
235
236 -- | Set all elements of the vector to the given value.
237 set :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> a -> m ()
238 {-# INLINE set #-}
239 set = G.set
240
241 -- | Copy a vector. The two vectors must have the same length and may not
242 -- overlap.
243 copy :: (PrimMonad m, Unbox a)
244 => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
245 {-# INLINE copy #-}
246 copy = G.copy
247
248 -- | Copy a vector. The two vectors must have the same length and may not
249 -- overlap. This is not checked.
250 unsafeCopy :: (PrimMonad m, Unbox a)
251 => MVector (PrimState m) a -- ^ target
252 -> MVector (PrimState m) a -- ^ source
253 -> m ()
254 {-# INLINE unsafeCopy #-}
255 unsafeCopy = G.unsafeCopy
256
257 -- | Move the contents of a vector. The two vectors must have the same
258 -- length.
259 --
260 -- If the vectors do not overlap, then this is equivalent to 'copy'.
261 -- Otherwise, the copying is performed as if the source vector were
262 -- copied to a temporary vector and then the temporary vector was copied
263 -- to the target vector.
264 move :: (PrimMonad m, Unbox a)
265 => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
266 {-# INLINE move #-}
267 move = G.move
268
269 -- | Move the contents of a vector. The two vectors must have the same
270 -- length, but this is not checked.
271 --
272 -- If the vectors do not overlap, then this is equivalent to 'unsafeCopy'.
273 -- Otherwise, the copying is performed as if the source vector were
274 -- copied to a temporary vector and then the temporary vector was copied
275 -- to the target vector.
276 unsafeMove :: (PrimMonad m, Unbox a)
277 => MVector (PrimState m) a -- ^ target
278 -> MVector (PrimState m) a -- ^ source
279 -> m ()
280 {-# INLINE unsafeMove #-}
281 unsafeMove = G.unsafeMove
282
283 #define DEFINE_MUTABLE
284 #include "unbox-tuple-instances"
285