Documentation only (for Data.Vector module)
[darcs-mirrors/vector.git] / Data / Vector.hs
1 {-# LANGUAGE FlexibleInstances, MultiParamTypeClasses, TypeFamilies #-}
2
3 -- |
4 -- Module : Data.Vector
5 -- Copyright : (c) Roman Leshchinskiy 2008-2009
6 -- License : BSD-style
7 --
8 -- Maintainer : Roman Leshchinskiy <rl@cse.unsw.edu.au>
9 -- Stability : experimental
10 -- Portability : non-portable
11 --
12 -- A library for boxed vectors (that is, polymorphic arrays capable of
13 -- holding any Haskell value). The vectors come in two flavors:
14 --
15 -- * mutable
16 --
17 -- * immutable
18 --
19 -- and support a rich interface of both list-like operations, and bulk
20 -- array operations.
21 --
22 -- For unboxed arrays, use the 'Data.Vector.Unboxed' interface.
23 --
24
25 module Data.Vector (
26
27 -- * The pure and mutable array types
28 Vector, MVector,
29
30 -- * Constructing vectors
31 empty,
32 singleton,
33 cons,
34 snoc,
35 (++),
36 replicate,
37 generate,
38 copy,
39
40 -- * Operations based on length information
41 length,
42 null,
43
44 -- * Accessing individual elements
45 (!),
46 head,
47 last,
48
49 -- ** Accessors in a monad
50 indexM,
51 headM,
52 lastM,
53
54 -- ** Accessor functions with no bounds checking
55 unsafeIndex, unsafeHead, unsafeLast,
56 unsafeIndexM, unsafeHeadM, unsafeLastM,
57
58 -- * Subvectors
59 init,
60 tail,
61 take,
62 drop,
63 slice,
64
65 -- * Subvector construction without bounds checks
66 unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,
67
68 -- * Permutations
69 accum, accumulate, accumulate_,
70 (//), update, update_,
71 backpermute, reverse,
72 unsafeAccum, unsafeAccumulate, unsafeAccumulate_,
73 unsafeUpd, unsafeUpdate, unsafeUpdate_,
74 unsafeBackpermute,
75
76 -- * Mapping
77 map, imap, concatMap,
78
79 -- * Zipping and unzipping
80 zipWith, zipWith3, zipWith4, zipWith5, zipWith6,
81 izipWith, izipWith3, izipWith4, izipWith5, izipWith6,
82 zip, zip3, zip4, zip5, zip6,
83 unzip, unzip3, unzip4, unzip5, unzip6,
84
85 -- * Filtering
86 filter, ifilter, takeWhile, dropWhile,
87 partition, unstablePartition, span, break,
88
89 -- * Searching
90 elem, notElem, find, findIndex, findIndices, elemIndex, elemIndices,
91
92 -- * Folding
93 foldl, foldl1, foldl', foldl1', foldr, foldr1, foldr', foldr1',
94 ifoldl, ifoldl', ifoldr, ifoldr',
95
96 -- * Specialised folds
97 all, any, and, or,
98 sum, product,
99 maximum, maximumBy, minimum, minimumBy,
100 minIndex, minIndexBy, maxIndex, maxIndexBy,
101
102 -- * Unfolding
103 unfoldr,
104
105 -- * Scans
106 prescanl, prescanl',
107 postscanl, postscanl',
108 scanl, scanl', scanl1, scanl1',
109 prescanr, prescanr',
110 postscanr, postscanr',
111 scanr, scanr', scanr1, scanr1',
112
113 -- * Enumeration
114 enumFromN, enumFromStepN, enumFromTo, enumFromThenTo,
115
116 -- * Conversion to/from lists
117 toList, fromList
118 ) where
119
120 import qualified Data.Vector.Generic as G
121 import Data.Vector.Mutable ( MVector(..) )
122 import Data.Primitive.Array
123
124 import Control.Monad ( liftM )
125
126 import Prelude hiding ( length, null,
127 replicate, (++),
128 head, last,
129 init, tail, take, drop, reverse,
130 map, concatMap,
131 zipWith, zipWith3, zip, zip3, unzip, unzip3,
132 filter, takeWhile, dropWhile, span, break,
133 elem, notElem,
134 foldl, foldl1, foldr, foldr1,
135 all, any, and, or, sum, product, minimum, maximum,
136 scanl, scanl1, scanr, scanr1,
137 enumFromTo, enumFromThenTo )
138
139 import qualified Prelude
140
141 -- | Boxed vectors, supporting efficient slicing.
142 data Vector a = Vector {-# UNPACK #-} !Int
143 {-# UNPACK #-} !Int
144 {-# UNPACK #-} !(Array a)
145
146 instance Show a => Show (Vector a) where
147 show = (Prelude.++ " :: Data.Vector.Vector") . ("fromList " Prelude.++) . show . toList
148
149 type instance G.Mutable Vector = MVector
150
151 instance G.Vector Vector a where
152 {-# INLINE unsafeFreeze #-}
153 unsafeFreeze (MVector i n marr)
154 = Vector i n `liftM` unsafeFreezeArray marr
155
156 {-# INLINE basicLength #-}
157 basicLength (Vector _ n _) = n
158
159 {-# INLINE basicUnsafeSlice #-}
160 basicUnsafeSlice j n (Vector i _ arr) = Vector (i+j) n arr
161
162 {-# INLINE basicUnsafeIndexM #-}
163 basicUnsafeIndexM (Vector i _ arr) j = indexArrayM arr (i+j)
164
165 instance Eq a => Eq (Vector a) where
166 {-# INLINE (==) #-}
167 (==) = G.eq
168
169 instance Ord a => Ord (Vector a) where
170 {-# INLINE compare #-}
171 compare = G.cmp
172
173 -- Length
174 -- ------
175
176 -- |/O(1)/. Yield the length of a vector as an 'Int'
177 length :: Vector a -> Int
178 {-# INLINE length #-}
179 length = G.length
180
181 -- |/O(1)/. 'null' tests whether the given array is empty.
182 null :: Vector a -> Bool
183 {-# INLINE null #-}
184 null = G.null
185
186 -- Construction
187 -- ------------
188
189 -- |/O(1)/. 'empty' builds a vector of size zero.
190 empty :: Vector a
191 {-# INLINE empty #-}
192 empty = G.empty
193
194 -- |/O(1)/, Vector with exactly one element
195 singleton :: a -> Vector a
196 {-# INLINE singleton #-}
197 singleton = G.singleton
198
199 -- |/O(n)/. @'replicate' n e@ yields a vector of length @n@ storing @e@ at each position
200 replicate :: Int -> a -> Vector a
201 {-# INLINE replicate #-}
202 replicate = G.replicate
203
204 -- |/O(n)/, Generate a vector of the given length by applying a (pure)
205 -- generator function to each index
206 generate :: Int -> (Int -> a) -> Vector a
207 {-# INLINE generate #-}
208 generate = G.generate
209
210 -- |/O(n)/, Prepend an element to an array.
211 cons :: a -> Vector a -> Vector a
212 {-# INLINE cons #-}
213 cons = G.cons
214
215 -- |/O(n)/, Append an element to an array.
216 snoc :: Vector a -> a -> Vector a
217 {-# INLINE snoc #-}
218 snoc = G.snoc
219
220 infixr 5 ++
221
222 -- |/O(n)/, Concatenate two vectors
223 (++) :: Vector a -> Vector a -> Vector a
224 {-# INLINE (++) #-}
225 (++) = (G.++)
226
227 -- |/O(n)/, Create a copy of a vector.
228 -- @copy@ is useful when dealing with slices, as the garbage collector
229 -- may be able to free the original vector if no further references are held.
230 --
231 copy :: Vector a -> Vector a
232 {-# INLINE copy #-}
233 copy = G.copy
234
235 -- Accessing individual elements
236 -- -----------------------------
237
238 -- |/O(1)/. Read the element in the vector at the given index.
239 (!) :: Vector a -> Int -> a
240 {-# INLINE (!) #-}
241 (!) = (G.!)
242
243 -- |/O(1)/. 'head' returns the first element of the vector
244 head :: Vector a -> a
245 {-# INLINE head #-}
246 head = G.head
247
248 -- |/O(n)/. 'last' yields the last element of an array.
249 last :: Vector a -> a
250 {-# INLINE last #-}
251 last = G.last
252
253 -- |/O(1)/, Unsafe indexing without bounds checking
254 --
255 -- By not performing bounds checks, this function may be faster when
256 -- this function is used in an inner loop)
257 --
258 unsafeIndex :: Vector a -> Int -> a
259 {-# INLINE unsafeIndex #-}
260 unsafeIndex = G.unsafeIndex
261
262 -- |/O(1)/, Yield the first element of a vector without checking if the vector is empty
263 --
264 -- By not performing bounds checks, this function may be faster when
265 -- this function is used in an inner loop)
266 unsafeHead :: Vector a -> a
267 {-# INLINE unsafeHead #-}
268 unsafeHead = G.unsafeHead
269
270 -- | Yield the last element of a vector without checking if the vector is empty
271 --
272 -- By not performing bounds checks, this function may be faster when
273 -- this function is used in an inner loop)
274 unsafeLast :: Vector a -> a
275 {-# INLINE unsafeLast #-}
276 unsafeLast = G.unsafeLast
277
278 -- | Monadic indexing which can be strict in the vector while remaining lazy in the element
279 indexM :: Monad m => Vector a -> Int -> m a
280 {-# INLINE indexM #-}
281 indexM = G.indexM
282
283 -- | Monadic head which can be strict in the vector while remaining lazy in the element
284 headM :: Monad m => Vector a -> m a
285 {-# INLINE headM #-}
286 headM = G.headM
287
288 -- | Monadic last which can be strict in the vector while remaining lazy in the element
289 lastM :: Monad m => Vector a -> m a
290 {-# INLINE lastM #-}
291 lastM = G.lastM
292
293 -- | Unsafe monadic indexing without bounds checks
294 unsafeIndexM :: Monad m => Vector a -> Int -> m a
295 {-# INLINE unsafeIndexM #-}
296 unsafeIndexM = G.unsafeIndexM
297
298 -- | Unsafe monadic head (access the first element) without bounds checks
299 unsafeHeadM :: Monad m => Vector a -> m a
300 {-# INLINE unsafeHeadM #-}
301 unsafeHeadM = G.unsafeHeadM
302
303 -- | Unsafe monadic last (access the last element) without bounds checks
304 unsafeLastM :: Monad m => Vector a -> m a
305 {-# INLINE unsafeLastM #-}
306 unsafeLastM = G.unsafeLastM
307
308 -- Subarrays
309 -- ---------
310
311 -- | /O(1)/, Yield a part of the vector without copying it.
312 --
313 slice :: Int -- ^ starting index
314 -> Int -- ^ length
315 -> Vector a
316 -> Vector a
317 {-# INLINE slice #-}
318 slice = G.slice
319
320 -- |/O(1)/, Yield all but the last element without copying.
321 init :: Vector a -> Vector a
322 {-# INLINE init #-}
323 init = G.init
324
325 -- |/O(1), Yield all but the first element (without copying).
326 tail :: Vector a -> Vector a
327 {-# INLINE tail #-}
328 tail = G.tail
329
330 -- |/O(1)/, Yield the first @n@ elements without copying.
331 take :: Int -> Vector a -> Vector a
332 {-# INLINE take #-}
333 take = G.take
334
335 -- |/O(1)/, Yield all but the first @n@ elements without copying.
336 drop :: Int -> Vector a -> Vector a
337 {-# INLINE drop #-}
338 drop = G.drop
339
340 -- |/O(1)/, Unsafely yield a part of the vector without copying it and without
341 -- performing bounds checks.
342 unsafeSlice :: Int -- ^ starting index
343 -> Int -- ^ length
344 -> Vector a
345 -> Vector a
346 {-# INLINE unsafeSlice #-}
347 unsafeSlice = G.unsafeSlice
348
349 -- |/O(1)/, Zero-copying 'init' without bounds checks.
350 unsafeInit :: Vector a -> Vector a
351 {-# INLINE unsafeInit #-}
352 unsafeInit = G.unsafeInit
353
354 -- |/O(1)/, Zero-copying 'tail' without bounds checks.
355 unsafeTail :: Vector a -> Vector a
356 {-# INLINE unsafeTail #-}
357 unsafeTail = G.unsafeTail
358
359 -- |/O(1)/, Zero-copying 'take' without bounds checks.
360 unsafeTake :: Int -> Vector a -> Vector a
361 {-# INLINE unsafeTake #-}
362 unsafeTake = G.unsafeTake
363
364 -- |/O(1)/, Zero-copying 'drop' without bounds checks.
365 unsafeDrop :: Int -> Vector a -> Vector a
366 {-# INLINE unsafeDrop #-}
367 unsafeDrop = G.unsafeDrop
368
369 -- Permutations
370 -- ------------
371
372 -- TODO there is no documentation for the accum* family of functions
373
374 -- | TODO unsafeAccum.
375 unsafeAccum :: (a -> b -> a) -> Vector a -> [(Int,b)] -> Vector a
376 {-# INLINE unsafeAccum #-}
377 unsafeAccum = G.unsafeAccum
378
379 -- | TODO unsafeAccumulate
380 unsafeAccumulate :: (a -> b -> a) -> Vector a -> Vector (Int,b) -> Vector a
381 {-# INLINE unsafeAccumulate #-}
382 unsafeAccumulate = G.unsafeAccumulate
383
384 -- | TODO unsafeAccumulate_
385 unsafeAccumulate_
386 :: (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a
387 {-# INLINE unsafeAccumulate_ #-}
388 unsafeAccumulate_ = G.unsafeAccumulate_
389
390 -- | TODO accum
391 accum :: (a -> b -> a) -> Vector a -> [(Int,b)] -> Vector a
392 {-# INLINE accum #-}
393 accum = G.accum
394
395 -- | TODO accumulate
396 accumulate :: (a -> b -> a) -> Vector a -> Vector (Int,b) -> Vector a
397 {-# INLINE accumulate #-}
398 accumulate = G.accumulate
399
400 -- | TODO accumulate_
401 accumulate_ :: (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a
402 {-# INLINE accumulate_ #-}
403 accumulate_ = G.accumulate_
404
405 -- | TODO unsafeUpd
406 unsafeUpd :: Vector a -> [(Int, a)] -> Vector a
407 {-# INLINE unsafeUpd #-}
408 unsafeUpd = G.unsafeUpd
409
410 -- | TODO unsafeUpdate
411 unsafeUpdate :: Vector a -> Vector (Int, a) -> Vector a
412 {-# INLINE unsafeUpdate #-}
413 unsafeUpdate = G.unsafeUpdate
414
415 -- | TODO unsafeUpdate_
416 unsafeUpdate_ :: Vector a -> Vector Int -> Vector a -> Vector a
417 {-# INLINE unsafeUpdate_ #-}
418 unsafeUpdate_ = G.unsafeUpdate_
419
420 -- | TODO (//)
421 (//) :: Vector a -> [(Int, a)] -> Vector a
422 {-# INLINE (//) #-}
423 (//) = (G.//)
424
425 -- | TODO update
426 update :: Vector a -> Vector (Int, a) -> Vector a
427 {-# INLINE update #-}
428 update = G.update
429
430 -- | TODO update_
431 update_ :: Vector a -> Vector Int -> Vector a -> Vector a
432 {-# INLINE update_ #-}
433 update_ = G.update_
434
435 -- | backpermute, courtesy Blelloch. The back-permute is a gather\/get operation.
436 backpermute :: Vector a -> Vector Int -> Vector a
437 {-# INLINE backpermute #-}
438 backpermute = G.backpermute
439
440 -- | TODO unsafeBackpermute
441 unsafeBackpermute :: Vector a -> Vector Int -> Vector a
442 {-# INLINE unsafeBackpermute #-}
443 unsafeBackpermute = G.unsafeBackpermute
444
445 -- | /O(n)/, reverse the elements of the given vector.
446 reverse :: Vector a -> Vector a
447 {-# INLINE reverse #-}
448 reverse = G.reverse
449
450 -- Mapping
451 -- -------
452
453 -- | /O(n)/, Map a function over a vector
454 map :: (a -> b) -> Vector a -> Vector b
455 {-# INLINE map #-}
456 map = G.map
457
458 -- | /O(n)/, Apply a function to every index/value pair yielding a new vector
459 imap :: (Int -> a -> b) -> Vector a -> Vector b
460 {-# INLINE imap #-}
461 imap = G.imap
462
463 -- | /O(n)/, generate a vector from each element of the input vector, then join the results.
464 concatMap :: (a -> Vector b) -> Vector a -> Vector b
465 {-# INLINE concatMap #-}
466 concatMap = G.concatMap
467
468 -- Zipping/unzipping
469 -- -----------------
470
471 -- |/O(n)/, Zip two vectors with the given function.
472 zipWith :: (a -> b -> c) -> Vector a -> Vector b -> Vector c
473 {-# INLINE zipWith #-}
474 zipWith = G.zipWith
475
476 -- |/O(n)/, Zip three vectors with the given function.
477 zipWith3 :: (a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
478 {-# INLINE zipWith3 #-}
479 zipWith3 = G.zipWith3
480
481 -- |/O(n)/, Zip four vectors with the given function.
482 zipWith4 :: (a -> b -> c -> d -> e)
483 -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
484 {-# INLINE zipWith4 #-}
485 zipWith4 = G.zipWith4
486
487 -- |/O(n)/, Zip five vectors with the given function.
488 zipWith5 :: (a -> b -> c -> d -> e -> f)
489 -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
490 -> Vector f
491 {-# INLINE zipWith5 #-}
492 zipWith5 = G.zipWith5
493
494 -- |/O(n)/, Zip six vectors with the given function.
495 zipWith6 :: (a -> b -> c -> d -> e -> f -> g)
496 -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
497 -> Vector f -> Vector g
498 {-# INLINE zipWith6 #-}
499 zipWith6 = G.zipWith6
500
501 -- |/O(n)/, Zip two vectors and their indices with the given function.
502 izipWith :: (Int -> a -> b -> c) -> Vector a -> Vector b -> Vector c
503 {-# INLINE izipWith #-}
504 izipWith = G.izipWith
505
506 -- |/O(n)/, Zip three vectors and their indices with the given function.
507 izipWith3 :: (Int -> a -> b -> c -> d)
508 -> Vector a -> Vector b -> Vector c -> Vector d
509 {-# INLINE izipWith3 #-}
510 izipWith3 = G.izipWith3
511
512 -- |/O(n)/, Zip four vectors and their indices with the given function.
513 izipWith4 :: (Int -> a -> b -> c -> d -> e)
514 -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
515 {-# INLINE izipWith4 #-}
516 izipWith4 = G.izipWith4
517
518 -- |/O(n)/, Zip five vectors and their indices with the given function.
519 izipWith5 :: (Int -> a -> b -> c -> d -> e -> f)
520 -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
521 -> Vector f
522 {-# INLINE izipWith5 #-}
523 izipWith5 = G.izipWith5
524
525 -- |/O(n)/, Zip six vectors and their indices with the given function.
526 izipWith6 :: (Int -> a -> b -> c -> d -> e -> f -> g)
527 -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
528 -> Vector f -> Vector g
529 {-# INLINE izipWith6 #-}
530 izipWith6 = G.izipWith6
531
532 -- | Elementwise pairing of array elements.
533 zip :: Vector a -> Vector b -> Vector (a, b)
534 {-# INLINE zip #-}
535 zip = G.zip
536
537 -- | zip together three vectors into a vector of triples
538 zip3 :: Vector a -> Vector b -> Vector c -> Vector (a, b, c)
539 {-# INLINE zip3 #-}
540 zip3 = G.zip3
541
542 zip4 :: Vector a -> Vector b -> Vector c -> Vector d
543 -> Vector (a, b, c, d)
544 {-# INLINE zip4 #-}
545 zip4 = G.zip4
546
547 zip5 :: Vector a -> Vector b -> Vector c -> Vector d -> Vector e
548 -> Vector (a, b, c, d, e)
549 {-# INLINE zip5 #-}
550 zip5 = G.zip5
551
552 zip6 :: Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f
553 -> Vector (a, b, c, d, e, f)
554 {-# INLINE zip6 #-}
555 zip6 = G.zip6
556
557 -- | Elementwise unpairing of array elements.
558 unzip :: Vector (a, b) -> (Vector a, Vector b)
559 {-# INLINE unzip #-}
560 unzip = G.unzip
561
562 unzip3 :: Vector (a, b, c) -> (Vector a, Vector b, Vector c)
563 {-# INLINE unzip3 #-}
564 unzip3 = G.unzip3
565
566 unzip4 :: Vector (a, b, c, d) -> (Vector a, Vector b, Vector c, Vector d)
567 {-# INLINE unzip4 #-}
568 unzip4 = G.unzip4
569
570 unzip5 :: Vector (a, b, c, d, e)
571 -> (Vector a, Vector b, Vector c, Vector d, Vector e)
572 {-# INLINE unzip5 #-}
573 unzip5 = G.unzip5
574
575 unzip6 :: Vector (a, b, c, d, e, f)
576 -> (Vector a, Vector b, Vector c, Vector d, Vector e, Vector f)
577 {-# INLINE unzip6 #-}
578 unzip6 = G.unzip6
579
580 -- Filtering
581 -- ---------
582
583 -- |/O(n)/, Remove elements from the vector which do not satisfy the predicate
584 filter :: (a -> Bool) -> Vector a -> Vector a
585 {-# INLINE filter #-}
586 filter = G.filter
587
588 -- |/O(n)/, Drop elements that do not satisfy the predicate (applied to values and
589 -- their indices)
590 ifilter :: (Int -> a -> Bool) -> Vector a -> Vector a
591 {-# INLINE ifilter #-}
592 ifilter = G.ifilter
593
594 -- |/O(n)/, Yield the longest prefix of elements satisfying the predicate.
595 takeWhile :: (a -> Bool) -> Vector a -> Vector a
596 {-# INLINE takeWhile #-}
597 takeWhile = G.takeWhile
598
599 -- |/O(n)/, Drop the longest prefix of elements that satisfy the predicate.
600 dropWhile :: (a -> Bool) -> Vector a -> Vector a
601 {-# INLINE dropWhile #-}
602 dropWhile = G.dropWhile
603
604 -- | Split the vector in two parts, the first one containing those elements
605 -- that satisfy the predicate and the second one those that don't. The
606 -- relative order of the elements is preserved at the cost of a (sometimes)
607 -- reduced performance compared to 'unstablePartition'.
608 partition :: (a -> Bool) -> Vector a -> (Vector a, Vector a)
609 {-# INLINE partition #-}
610 partition = G.partition
611
612 -- |/O(n)/, Split the vector in two parts, the first one containing those elements
613 -- that satisfy the predicate and the second one those that don't. The order
614 -- of the elements is not preserved.
615 unstablePartition :: (a -> Bool) -> Vector a -> (Vector a, Vector a)
616 {-# INLINE unstablePartition #-}
617 unstablePartition = G.unstablePartition
618
619 -- |/O(n)/, Split the vector into the longest prefix of elements that satisfy the
620 -- predicate and the rest.
621 span :: (a -> Bool) -> Vector a -> (Vector a, Vector a)
622 {-# INLINE span #-}
623 span = G.span
624
625 -- | Split the vector into the longest prefix of elements that do not satisfy
626 -- the predicate and the rest.
627 break :: (a -> Bool) -> Vector a -> (Vector a, Vector a)
628 {-# INLINE break #-}
629 break = G.break
630
631 -- Searching
632 -- ---------
633
634 infix 4 `elem`
635 -- | Check whether the vector contains an element
636 elem :: Eq a => a -> Vector a -> Bool
637 {-# INLINE elem #-}
638 elem = G.elem
639
640 infix 4 `notElem`
641 -- | Inverse of `elem`
642 notElem :: Eq a => a -> Vector a -> Bool
643 {-# INLINE notElem #-}
644 notElem = G.notElem
645
646 -- | Yield 'Just' the first element matching the predicate or 'Nothing' if no
647 -- such element exists.
648 find :: (a -> Bool) -> Vector a -> Maybe a
649 {-# INLINE find #-}
650 find = G.find
651
652 -- | Yield 'Just' the index of the first element matching the predicate or
653 -- 'Nothing' if no such element exists.
654 findIndex :: (a -> Bool) -> Vector a -> Maybe Int
655 {-# INLINE findIndex #-}
656 findIndex = G.findIndex
657
658 -- | Yield the indices of elements satisfying the predicate
659 findIndices :: (a -> Bool) -> Vector a -> Vector Int
660 {-# INLINE findIndices #-}
661 findIndices = G.findIndices
662
663 -- | Yield 'Just' the index of the first occurence of the given element or
664 -- 'Nothing' if the vector does not contain the element
665 elemIndex :: Eq a => a -> Vector a -> Maybe Int
666 {-# INLINE elemIndex #-}
667 elemIndex = G.elemIndex
668
669 -- | Yield the indices of all occurences of the given element
670 elemIndices :: Eq a => a -> Vector a -> Vector Int
671 {-# INLINE elemIndices #-}
672 elemIndices = G.elemIndices
673
674 -- Folding
675 -- -------
676
677 -- | Left fold
678 foldl :: (a -> b -> a) -> a -> Vector b -> a
679 {-# INLINE foldl #-}
680 foldl = G.foldl
681
682 -- | Left fold on non-empty vectors
683 foldl1 :: (a -> a -> a) -> Vector a -> a
684 {-# INLINE foldl1 #-}
685 foldl1 = G.foldl1
686
687 -- | Left fold with strict accumulator
688 foldl' :: (a -> b -> a) -> a -> Vector b -> a
689 {-# INLINE foldl' #-}
690 foldl' = G.foldl'
691
692 -- | Left fold on non-empty vectors with strict accumulator
693 foldl1' :: (a -> a -> a) -> Vector a -> a
694 {-# INLINE foldl1' #-}
695 foldl1' = G.foldl1'
696
697 -- | Right fold
698 foldr :: (a -> b -> b) -> b -> Vector a -> b
699 {-# INLINE foldr #-}
700 foldr = G.foldr
701
702 -- | Right fold on non-empty vectors
703 foldr1 :: (a -> a -> a) -> Vector a -> a
704 {-# INLINE foldr1 #-}
705 foldr1 = G.foldr1
706
707 -- | Right fold with a strict accumulator
708 foldr' :: (a -> b -> b) -> b -> Vector a -> b
709 {-# INLINE foldr' #-}
710 foldr' = G.foldr'
711
712 -- | Right fold on non-empty vectors with strict accumulator
713 foldr1' :: (a -> a -> a) -> Vector a -> a
714 {-# INLINE foldr1' #-}
715 foldr1' = G.foldr1'
716
717 -- | Left fold (function applied to each element and its index)
718 ifoldl :: (a -> Int -> b -> a) -> a -> Vector b -> a
719 {-# INLINE ifoldl #-}
720 ifoldl = G.ifoldl
721
722 -- | Left fold with strict accumulator (function applied to each element and
723 -- its index)
724 ifoldl' :: (a -> Int -> b -> a) -> a -> Vector b -> a
725 {-# INLINE ifoldl' #-}
726 ifoldl' = G.ifoldl'
727
728 -- | Right fold (function applied to each element and its index)
729 ifoldr :: (Int -> a -> b -> b) -> b -> Vector a -> b
730 {-# INLINE ifoldr #-}
731 ifoldr = G.ifoldr
732
733 -- | Right fold with strict accumulator (function applied to each element and
734 -- its index)
735 ifoldr' :: (Int -> a -> b -> b) -> b -> Vector a -> b
736 {-# INLINE ifoldr' #-}
737 ifoldr' = G.ifoldr'
738
739 -- Specialised folds
740 -- -----------------
741
742 -- |/O(n)/. @'all' p u@ determines whether all elements in array @u@ satisfy
743 -- predicate @p@.
744 all :: (a -> Bool) -> Vector a -> Bool
745 {-# INLINE all #-}
746 all = G.all
747
748 -- |/O(n)/. @'any' p u@ determines whether any element in array @u@ satisfies
749 -- predicate @p@.
750 any :: (a -> Bool) -> Vector a -> Bool
751 {-# INLINE any #-}
752 any = G.any
753
754 -- |/O(n)/. 'and' yields the conjunction of a boolean array.
755 and :: Vector Bool -> Bool
756 {-# INLINE and #-}
757 and = G.and
758
759 -- |/O(n)/. 'or' yields the disjunction of a boolean array.
760 or :: Vector Bool -> Bool
761 {-# INLINE or #-}
762 or = G.or
763
764 -- |/O(n)/. 'sum' computes the sum (with @(+)@) of an array of elements.
765 sum :: Num a => Vector a -> a
766 {-# INLINE sum #-}
767 sum = G.sum
768
769 -- |/O(n)/. 'sum' computes the product (with @(*)@) of an array of elements.
770 product :: Num a => Vector a -> a
771 {-# INLINE product #-}
772 product = G.product
773
774 -- |/O(n)/. 'maximum' finds the maximum element in an array of orderable elements.
775 maximum :: Ord a => Vector a -> a
776 {-# INLINE maximum #-}
777 maximum = G.maximum
778
779 -- |/O(n)/. 'maximumBy' finds the maximum element in an array under the given ordering.
780 maximumBy :: (a -> a -> Ordering) -> Vector a -> a
781 {-# INLINE maximumBy #-}
782 maximumBy = G.maximumBy
783
784 -- |/O(n)/. 'minimum' finds the minimum element in an array of orderable elements.
785 minimum :: Ord a => Vector a -> a
786 {-# INLINE minimum #-}
787 minimum = G.minimum
788
789 -- |/O(n)/. 'minimumBy' finds the minimum element in an array under the given ordering.
790 minimumBy :: (a -> a -> Ordering) -> Vector a -> a
791 {-# INLINE minimumBy #-}
792 minimumBy = G.minimumBy
793
794 -- | TODO maxIndex
795 maxIndex :: Ord a => Vector a -> Int
796 {-# INLINE maxIndex #-}
797 maxIndex = G.maxIndex
798
799 -- | TODO maxIndexBy
800 maxIndexBy :: (a -> a -> Ordering) -> Vector a -> Int
801 {-# INLINE maxIndexBy #-}
802 maxIndexBy = G.maxIndexBy
803
804 -- | TODO minIndex
805 minIndex :: Ord a => Vector a -> Int
806 {-# INLINE minIndex #-}
807 minIndex = G.minIndex
808
809 -- | TODO minIndexBy
810 minIndexBy :: (a -> a -> Ordering) -> Vector a -> Int
811 {-# INLINE minIndexBy #-}
812 minIndexBy = G.minIndexBy
813
814 -- Unfolding
815 -- ---------
816
817 -- | The 'unfoldr' function is a \`dual\' to 'foldr': while 'foldr'
818 -- reduces a vector to a summary value, 'unfoldr' builds a list from
819 -- a seed value. The function takes the element and returns 'Nothing'
820 -- if it is done generating the vector or returns 'Just' @(a,b)@, in which
821 -- case, @a@ is a prepended to the vector and @b@ is used as the next
822 -- element in a recursive call.
823 --
824 -- A simple use of unfoldr:
825 --
826 -- > unfoldr (\b -> if b == 0 then Nothing else Just (b, b-1)) 10
827 -- > [10,9,8,7,6,5,4,3,2,1]
828 --
829 unfoldr :: (b -> Maybe (a, b)) -> b -> Vector a
830 {-# INLINE unfoldr #-}
831 unfoldr = G.unfoldr
832
833 -- Scans
834 -- -----
835
836 -- | Prefix scan
837 prescanl :: (a -> b -> a) -> a -> Vector b -> Vector a
838 {-# INLINE prescanl #-}
839 prescanl = G.prescanl
840
841 -- | Prefix scan with strict accumulator
842 prescanl' :: (a -> b -> a) -> a -> Vector b -> Vector a
843 {-# INLINE prescanl' #-}
844 prescanl' = G.prescanl'
845
846 -- | Suffix scan
847 postscanl :: (a -> b -> a) -> a -> Vector b -> Vector a
848 {-# INLINE postscanl #-}
849 postscanl = G.postscanl
850
851 -- | Suffix scan with strict accumulator
852 postscanl' :: (a -> b -> a) -> a -> Vector b -> Vector a
853 {-# INLINE postscanl' #-}
854 postscanl' = G.postscanl'
855
856 -- | Haskell-style scan function.
857 scanl :: (a -> b -> a) -> a -> Vector b -> Vector a
858 {-# INLINE scanl #-}
859 scanl = G.scanl
860
861 -- | Haskell-style scan with strict accumulator
862 scanl' :: (a -> b -> a) -> a -> Vector b -> Vector a
863 {-# INLINE scanl' #-}
864 scanl' = G.scanl'
865
866 -- | Scan over a non-empty 'Vector'
867 scanl1 :: (a -> a -> a) -> Vector a -> Vector a
868 {-# INLINE scanl1 #-}
869 scanl1 = G.scanl1
870
871 -- | Scan over a non-empty 'Vector' with a strict accumulator
872 scanl1' :: (a -> a -> a) -> Vector a -> Vector a
873 {-# INLINE scanl1' #-}
874 scanl1' = G.scanl1'
875
876 -- | Prefix right-to-left scan
877 prescanr :: (a -> b -> b) -> b -> Vector a -> Vector b
878 {-# INLINE prescanr #-}
879 prescanr = G.prescanr
880
881 -- | Prefix right-to-left scan with strict accumulator
882 prescanr' :: (a -> b -> b) -> b -> Vector a -> Vector b
883 {-# INLINE prescanr' #-}
884 prescanr' = G.prescanr'
885
886 -- | Suffix right-to-left scan
887 postscanr :: (a -> b -> b) -> b -> Vector a -> Vector b
888 {-# INLINE postscanr #-}
889 postscanr = G.postscanr
890
891 -- | Suffix right-to-left scan with strict accumulator
892 postscanr' :: (a -> b -> b) -> b -> Vector a -> Vector b
893 {-# INLINE postscanr' #-}
894 postscanr' = G.postscanr'
895
896 -- | Haskell-style right-to-left scan
897 scanr :: (a -> b -> b) -> b -> Vector a -> Vector b
898 {-# INLINE scanr #-}
899 scanr = G.scanr
900
901 -- | Haskell-style right-to-left scan with strict accumulator
902 scanr' :: (a -> b -> b) -> b -> Vector a -> Vector b
903 {-# INLINE scanr' #-}
904 scanr' = G.scanr'
905
906 -- | Right-to-left scan over a non-empty vector
907 scanr1 :: (a -> a -> a) -> Vector a -> Vector a
908 {-# INLINE scanr1 #-}
909 scanr1 = G.scanr1
910
911 -- | Right-to-left scan over a non-empty vector with a strict accumulator
912 scanr1' :: (a -> a -> a) -> Vector a -> Vector a
913 {-# INLINE scanr1' #-}
914 scanr1' = G.scanr1'
915
916 -- Enumeration
917 -- -----------
918
919 -- | Yield a vector of the given length containing the values @x@, @x+1@ etc.
920 -- This operation is usually more efficient than 'enumFromTo'.
921 enumFromN :: Num a => a -> Int -> Vector a
922 {-# INLINE enumFromN #-}
923 enumFromN = G.enumFromN
924
925 -- | Yield a vector of the given length containing the values @x@, @x+y@,
926 -- @x+y+y@ etc. This operations is usually more efficient than
927 -- 'enumFromThenTo'.
928 enumFromStepN :: Num a => a -> a -> Int -> Vector a
929 {-# INLINE enumFromStepN #-}
930 enumFromStepN = G.enumFromStepN
931
932 -- | Enumerate values from @x@ to @y@.
933 --
934 -- /WARNING:/ This operation can be very inefficient. If at all possible, use
935 -- 'enumFromN' instead.
936 enumFromTo :: Enum a => a -> a -> Vector a
937 {-# INLINE enumFromTo #-}
938 enumFromTo = G.enumFromTo
939
940 -- | Enumerate values from @x@ to @y@ with a specific step @z@.
941 --
942 -- /WARNING:/ This operation can be very inefficient. If at all possible, use
943 -- 'enumFromStepN' instead.
944 enumFromThenTo :: Enum a => a -> a -> a -> Vector a
945 {-# INLINE enumFromThenTo #-}
946 enumFromThenTo = G.enumFromThenTo
947
948 -- Conversion to/from lists
949 -- ------------------------
950
951 -- | Convert a vector to a list
952 toList :: Vector a -> [a]
953 {-# INLINE toList #-}
954 toList = G.toList
955
956 -- | Convert a list to a vector
957 fromList :: [a] -> Vector a
958 {-# INLINE fromList #-}
959 fromList = G.fromList
960