Fix doc typo
[darcs-mirrors/vector.git] / Data / Vector / Unboxed.hs
index ef9b0a5..7d65408 100644 (file)
@@ -45,7 +45,7 @@ module Data.Vector.Unboxed (
   length, null,
 
   -- ** Indexing
-  (!), head, last,
+  (!), (!?), head, last,
   unsafeIndex, unsafeHead, unsafeLast,
 
   -- ** Monadic indexing
@@ -53,7 +53,7 @@ module Data.Vector.Unboxed (
   unsafeIndexM, unsafeHeadM, unsafeLastM,
 
   -- ** Extracting subvectors (slicing)
-  slice, init, tail, take, drop,
+  slice, init, tail, take, drop, splitAt,
   unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,
 
   -- * Construction
@@ -71,7 +71,7 @@ module Data.Vector.Unboxed (
   enumFromN, enumFromStepN, enumFromTo, enumFromThenTo,
 
   -- ** Concatenation
-  cons, snoc, (++),
+  cons, snoc, (++), concat,
 
   -- ** Restricting memory usage
   force,
@@ -94,6 +94,9 @@ module Data.Vector.Unboxed (
 
   -- * Elementwise operations
 
+  -- ** Indexing
+  indexed,
+
   -- ** Mapping
   map, imap, concatMap,
 
@@ -149,21 +152,25 @@ module Data.Vector.Unboxed (
   -- ** Lists
   toList, fromList, fromListN,
 
+  -- ** Other vector types
+  G.convert,
+
   -- ** Mutable vectors
-  thaw, thawMany, copy, unsafeCopy
+  freeze, thaw, copy, unsafeFreeze, unsafeThaw, unsafeCopy
 ) where
 
 import Data.Vector.Unboxed.Base
 import qualified Data.Vector.Generic as G
 import qualified Data.Vector.Fusion.Stream as Stream
+import Data.Vector.Fusion.Util ( delayed_min )
 
 import Control.Monad.ST ( ST )
 import Control.Monad.Primitive
 
 import Prelude hiding ( length, null,
-                        replicate, (++),
+                        replicate, (++), concat,
                         head, last,
-                        init, tail, take, drop, reverse,
+                        init, tail, take, drop, splitAt, reverse,
                         map, concatMap,
                         zipWith, zipWith3, zip, zip3, unzip, unzip3,
                         filter, takeWhile, dropWhile, span, break,
@@ -175,6 +182,8 @@ import Prelude hiding ( length, null,
                         mapM, mapM_ )
 import qualified Prelude
 
+import Data.Monoid   ( Monoid(..) )
+
 #include "vector.h"
 
 -- See http://trac.haskell.org/vector/ticket/12
@@ -202,6 +211,16 @@ instance (Unbox a, Ord a) => Ord (Vector a) where
   {-# INLINE (>=) #-}
   xs >= ys = Stream.cmp (G.stream xs) (G.stream ys) /= LT
 
+instance Unbox a => Monoid (Vector a) where
+  {-# INLINE mempty #-}
+  mempty = empty
+
+  {-# INLINE mappend #-}
+  mappend = (++)
+
+  {-# INLINE mconcat #-}
+  mconcat = concat
+
 instance (Show a, Unbox a) => Show (Vector a) where
     show = (Prelude.++ " :: Data.Vector.Unboxed.Vector") . ("fromList " Prelude.++) . show . toList
 
@@ -226,6 +245,11 @@ null = G.null
 {-# INLINE (!) #-}
 (!) = (G.!)
 
+-- | O(1) Safe indexing
+(!?) :: Unbox a => Vector a -> Int -> Maybe a
+{-# INLINE (!?) #-}
+(!?) = (G.!?)
+
 -- | /O(1)/ First element
 head :: Unbox a => Vector a -> a
 {-# INLINE head #-}
@@ -343,6 +367,14 @@ drop :: Unbox a => Int -> Vector a -> Vector a
 {-# INLINE drop #-}
 drop = G.drop
 
+-- | /O(1)/ Yield the first @n@ elements paired with the remainder without copying.
+--
+-- Note that @'splitAt' n v@ is equivalent to @('take' n v, 'drop' n v)@
+-- but slightly more efficient.
+{-# INLINE splitAt #-}
+splitAt :: Unbox a => Int -> Vector a -> (Vector a, Vector a)
+splitAt = G.splitAt
+
 -- | /O(1)/ Yield a slice of the vector without copying. The vector must
 -- contain at least @i+n@ elements but this is not checked.
 unsafeSlice :: Unbox a => Int   -- ^ @i@ starting index
@@ -476,6 +508,11 @@ infixr 5 ++
 {-# INLINE (++) #-}
 (++) = (G.++)
 
+-- | /O(n)/ Concatenate all vectors in the list
+concat :: Unbox a => [Vector a] -> Vector a
+{-# INLINE concat #-}
+concat = G.concat
+
 -- Monadic initialisation
 -- ----------------------
 
@@ -492,7 +529,8 @@ replicateM = G.replicateM
 -- @
 create :: Unbox a => (forall s. ST s (MVector s a)) -> Vector a
 {-# INLINE create #-}
-create = G.create
+-- NOTE: eta-expanded due to http://hackage.haskell.org/trac/ghc/ticket/4120
+create p = G.create p
 
 -- Restricting memory usage
 -- ------------------------
@@ -672,7 +710,15 @@ unsafeBackpermute = G.unsafeBackpermute
 -- @
 modify :: Unbox a => (forall s. MVector s a -> ST s ()) -> Vector a -> Vector a
 {-# INLINE modify #-}
-modify = G.modify
+modify p = G.modify p
+
+-- Indexing
+-- --------
+
+-- | /O(n)/ Pair each element in a vector with its index
+indexed :: Unbox a => Vector a -> Vector (Int,a)
+{-# INLINE indexed #-}
+indexed = G.indexed
 
 -- Mapping
 -- -------
@@ -1077,7 +1123,7 @@ foldM' :: (Monad m, Unbox b) => (a -> b -> m a) -> a -> Vector b -> m a
 {-# INLINE foldM' #-}
 foldM' = G.foldM'
 
--- | /O(n)/ Monad fold over non-empty vectors with strict accumulator
+-- | /O(n)/ Monadic fold over non-empty vectors with strict accumulator
 fold1M' :: (Monad m, Unbox a) => (a -> a -> m a) -> Vector a -> m a
 {-# INLINE fold1M' #-}
 fold1M' = G.fold1M'
@@ -1222,26 +1268,37 @@ fromListN = G.fromListN
 -- Conversions - Mutable vectors
 -- -----------------------------
 
+-- | /O(1)/ Unsafe convert a mutable vector to an immutable one without
+-- copying. The mutable vector may not be used after this operation.
+unsafeFreeze :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> m (Vector a)
+{-# INLINE unsafeFreeze #-}
+unsafeFreeze = G.unsafeFreeze
+
+-- | /O(1)/ Unsafely convert an immutable vector to a mutable one without
+-- copying. The immutable vector may not be used after this operation.
+unsafeThaw :: (Unbox a, PrimMonad m) => Vector a -> m (MVector (PrimState m) a)
+{-# INLINE unsafeThaw #-}
+unsafeThaw = G.unsafeThaw
+
 -- | /O(n)/ Yield a mutable copy of the immutable vector.
 thaw :: (Unbox a, PrimMonad m) => Vector a -> m (MVector (PrimState m) a)
 {-# INLINE thaw #-}
 thaw = G.thaw
 
--- | /O(n)/ Yield a mutable vector containing copies of each vector in the
--- list.
-thawMany :: (Unbox a, PrimMonad m) => [Vector a] -> m (MVector (PrimState m) a)
-{-# INLINE thawMany #-}
-thawMany = G.thawMany
+-- | /O(n)/ Yield an immutable copy of the mutable vector.
+freeze :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> m (Vector a)
+{-# INLINE freeze #-}
+freeze = G.freeze
 
 -- | /O(n)/ Copy an immutable vector into a mutable one. The two vectors must
--- have the same length.
+-- have the same length. This is not checked.
 unsafeCopy
   :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> Vector a -> m ()
 {-# INLINE unsafeCopy #-}
 unsafeCopy = G.unsafeCopy
            
 -- | /O(n)/ Copy an immutable vector into a mutable one. The two vectors must
--- have the same length. This is not checked.
+-- have the same length.
 copy :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> Vector a -> m ()
 {-# INLINE copy #-}
 copy = G.copy