Fusible (//)
[darcs-mirrors/vector.git] / Data / Vector / MVector.hs
index 32f358f..38f0e8d 100644 (file)
@@ -1,8 +1,22 @@
 {-# LANGUAGE MultiParamTypeClasses #-}
+-- |
+-- Module      : Data.Vector.MVector
+-- Copyright   : (c) Roman Leshchinskiy 2008
+-- License     : BSD-style
+--
+-- Maintainer  : rl@cse.unsw.edu.au
+-- Stability   : experimental
+-- Portability : non-portable
+-- 
+-- Generic interface to mutable vectors
+--
+
+#include "phases.h"
+
 module Data.Vector.MVector (
-  MVector(..),
+  MVectorPure(..), MVector(..),
 
-  slice, new, newWith, read, write, copy, grow, unstream
+  slice, new, newWith, read, write, copy, grow, unstream, update
 ) where
 
 import qualified Data.Vector.Stream      as Stream
@@ -21,21 +35,47 @@ import Prelude hiding ( length, read )
 gROWTH_FACTOR :: Double
 gROWTH_FACTOR = 1.5
 
-class Monad m => MVector v m a where
-  length           :: v m a -> Int
-  unsafeSlice      :: v m a -> Int -> Int -> v m a
+-- | Basic pure functions on mutable vectors
+class MVectorPure v a where
+  -- | Length of the mutable vector
+  length           :: v a -> Int
+
+  -- | Yield a part of the mutable vector without copying it. No range checks!
+  unsafeSlice      :: v a -> Int  -- ^ starting index
+                          -> Int  -- ^ length of the slice
+                          -> v a
+
+  -- Check whether two vectors overlap.
+  overlaps         :: v a -> v a -> Bool
+
+-- | Class of mutable vectors. The type @m@ is the monad in which the mutable
+-- vector can be transformed and @a@ is the type of elements.
+--
+class (Monad m, MVectorPure v a) => MVector v m a where
+  -- | Create a mutable vector of the given length. Length is not checked!
+  unsafeNew        :: Int -> m (v a)
+
+  -- | Create a mutable vector of the given length and fill it with an
+  -- initial value. Length is not checked!
+  unsafeNewWith    :: Int -> a -> m (v a)
 
-  unsafeNew        :: Int -> m (v m a)
-  unsafeNewWith    :: Int -> a -> m (v m a)
+  -- | Yield the element at the given position. Index is not checked!
+  unsafeRead       :: v a -> Int -> m a
 
-  unsafeRead       :: v m a -> Int -> m a
-  unsafeWrite      :: v a -> Int -> a -> m ()
+  -- | Replace the element at the given position. Index is not checked!
+  unsafeWrite      :: v a -> Int -> a -> m ()
 
-  set              :: v m a -> a -> m ()
-  unsafeCopy       :: v m a -> v m a -> m ()
-  unsafeGrow       :: v m a -> Int -> m (v m a)
+  -- | Write the value at each position.
+  set              :: v a -> a -> m ()
 
-  overlaps         :: v m a -> v m a -> Bool
+  -- | Copy a vector. The two vectors may not overlap. This is not checked!
+  unsafeCopy       :: v a   -- ^ target
+                   -> v a   -- ^ source
+                   -> m ()
+
+  -- | Grow a vector by the given number of elements. The length is not
+  -- checked!
+  unsafeGrow       :: v a -> Int -> m (v a)
 
   {-# INLINE unsafeNewWith #-}
   unsafeNewWith n x = do
@@ -72,49 +112,66 @@ class Monad m => MVector v m a where
     where
       n = length v
 
-inBounds :: MVector v m a => v m a -> Int -> Bool
+-- | Test whether the index is valid for the vector
+inBounds :: MVectorPure v a => v a -> Int -> Bool
 {-# INLINE inBounds #-}
 inBounds v i = i >= 0 && i < length v
 
-slice :: MVector v m a => v m a -> Int -> Int -> v m a
+-- | Yield a part of the mutable vector without copying it. Safer version of
+-- 'unsafeSlice'.
+slice :: MVectorPure v a => v a -> Int -> Int -> v a
 {-# INLINE slice #-}
 slice v i n = assert (i >=0 && n >= 0 && i+n <= length v)
             $ unsafeSlice v i n
 
-new :: MVector v m a => Int -> m (v m a)
+-- | Create a mutable vector of the given length. Safer version of
+-- 'unsafeNew'.
+new :: MVector v m a => Int -> m (v a)
 {-# INLINE new #-}
 new n = assert (n >= 0) $ unsafeNew n
 
-newWith :: MVector v m a => Int -> a -> m (v m a)
+-- | Create a mutable vector of the given length and fill it with an
+-- initial value. Safer version of 'unsafeNewWith'.
+newWith :: MVector v m a => Int -> a -> m (v a)
 {-# INLINE newWith #-}
 newWith n x = assert (n >= 0) $ unsafeNewWith n x
 
-read :: MVector v m a => v m a -> Int -> m a
+-- | Yield the element at the given position. Safer version of 'unsafeRead'.
+read :: MVector v m a => v a -> Int -> m a
 {-# INLINE read #-}
 read v i = assert (inBounds v i) $ unsafeRead v i
 
-write :: MVector v m a => v m a -> Int -> a -> m ()
+-- | Replace the element at the given position. Safer version of
+-- 'unsafeWrite'.
+write :: MVector v m a => v a -> Int -> a -> m ()
 {-# INLINE write #-}
 write v i x = assert (inBounds v i) $ unsafeWrite v i x
 
-copy :: MVector v m a => v m a -> v m a -> m ()
+-- | Copy a vector. The two vectors may not overlap. Safer version of
+-- 'unsafeCopy'.
+copy :: MVector v m a => v a -> v a -> m ()
 {-# INLINE copy #-}
 copy dst src = assert (not (dst `overlaps` src) && length dst == length src)
              $ unsafeCopy dst src
 
-grow :: MVector v m a => v m a -> Int -> m (v m a)
+-- | Grow a vector by the given number of elements. Safer version of
+-- 'unsafeGrow'.
+grow :: MVector v m a => v a -> Int -> m (v a)
 {-# INLINE grow #-}
 grow v by = assert (by >= 0)
           $ unsafeGrow v by
 
 
-unstream :: MVector v m a => Stream a -> m (v m a)
-{-# INLINE unstream #-}
+-- | Create a new mutable vector and fill it with elements from the 'Stream'.
+-- The vector will grow logarithmically if the 'Size' hint of the 'Stream' is
+-- inexact.
+unstream :: MVector v m a => Stream a -> m (v a)
+{-# INLINE_STREAM unstream #-}
 unstream s = case upperBound (Stream.size s) of
                Just n  -> unstreamMax     s n
                Nothing -> unstreamUnknown s
 
-unstreamMax :: MVector v m a => Stream a -> Int -> m (v a)
+unstreamMax :: MVector v m a => Stream a -> Int -> m (v a)
 {-# INLINE unstreamMax #-}
 unstreamMax s n
   = do
@@ -123,7 +180,7 @@ unstreamMax s n
       n' <- Stream.foldM put 0 s
       return $ slice v 0 n'
 
-unstreamUnknown :: MVector v m a => Stream a -> m (v a)
+unstreamUnknown :: MVector v m a => Stream a -> m (v a)
 {-# INLINE unstreamUnknown #-}
 unstreamUnknown s
   = do
@@ -144,3 +201,11 @@ unstreamUnknown s
                                  . double2Int
                                  $ int2Double (length v) * gROWTH_FACTOR
 
+
+update :: MVector v m a => v a -> Stream (Int, a) -> m ()
+{-# INLINE update #-}
+update v s = Stream.mapM_ put s
+  where
+    {-# INLINE put #-}
+    put (i, x) = write v i x
+