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