Sanitise Mutable exports and reorder code
authorRoman Leshchinskiy <rl@cse.unsw.edu.au>
Wed, 5 May 2010 16:40:12 +0000 (16:40 +0000)
committerRoman Leshchinskiy <rl@cse.unsw.edu.au>
Wed, 5 May 2010 16:40:12 +0000 (16:40 +0000)
Data/Vector/Generic/Mutable.hs
Data/Vector/Mutable.hs
Data/Vector/Primitive/Mutable.hs
Data/Vector/Storable/Mutable.hs
Data/Vector/Unboxed/Mutable.hs

index 278a6c2..1c056a5 100644 (file)
@@ -15,15 +15,37 @@ module Data.Vector.Generic.Mutable (
   -- * Class of mutable vector types
   MVector(..),
 
-  -- * Operations on mutable vectors
-  length, overlaps, new, replicate, read, write, swap, clear, set, copy, grow,
+  -- * Accessors
 
-  slice, take, drop, init, tail,
-  unsafeSlice, unsafeTake, unsafeDrop, unsafeInit, unsafeTail,
+  -- ** Length information
+  length, null,
 
-  -- * Unsafe operations
-  unsafeNew, unsafeRead, unsafeWrite, unsafeSwap,
-  unsafeCopy, unsafeGrow,
+  -- ** Extracting subvectors
+  slice, init, tail, take, drop,
+  unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,
+
+  -- ** Overlapping
+  overlaps,
+
+  -- * Construction
+
+  -- ** Initialisation
+  new, unsafeNew, replicate,
+
+  -- ** Growing
+  grow, unsafeGrow,
+
+  -- ** Restricting memory usage
+  clear,
+
+  -- * Accessing individual elements
+  read, write, swap,
+  unsafeRead, unsafeWrite, unsafeSwap,
+
+  -- * Modifying vectors
+
+  -- ** Filling and copying
+  set, copy, unsafeCopy,
 
   -- * Internal operations
   unstream, unstreamR,
@@ -45,7 +67,7 @@ import           Data.Vector.Fusion.Util        ( delay_inline )
 
 import Control.Monad.Primitive ( PrimMonad, PrimState )
 
-import Prelude hiding ( length, replicate, reverse, map, read,
+import Prelude hiding ( length, null, replicate, reverse, map, read,
                         take, drop, init, tail )
 
 #include "vector.h"
@@ -157,11 +179,6 @@ class MVector v a where
 -- Internal functions
 -- ------------------
 
--- Check whether two vectors overlap.
-overlaps :: MVector v a => v s a -> v s a -> Bool
-{-# INLINE overlaps #-}
-overlaps = basicOverlaps
-
 unsafeAppend1 :: (PrimMonad m, MVector v a)
         => v (PrimState m) a -> Int -> a -> m (v (PrimState m) a)
 {-# INLINE_INNER unsafeAppend1 #-}
@@ -374,73 +391,8 @@ null :: MVector v a => v s a -> Bool
 {-# INLINE null #-}
 null v = length v == 0
 
-
--- Accessing individual elements
--- -----------------------------
-
--- | Yield the element at the given position.
-read :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> m a
-{-# INLINE read #-}
-read v i = BOUNDS_CHECK(checkIndex) "read" i (length v)
-         $ unsafeRead v i
-
--- | Replace the element at the given position.
-write :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> a -> m ()
-{-# INLINE write #-}
-write v i x = BOUNDS_CHECK(checkIndex) "write" i (length v)
-            $ unsafeWrite v i x
-
--- | Swap the elements at the given positions.
-swap :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> Int -> m ()
-{-# INLINE swap #-}
-swap v i j = BOUNDS_CHECK(checkIndex) "swap" i (length v)
-           $ BOUNDS_CHECK(checkIndex) "swap" j (length v)
-           $ unsafeSwap v i j
-
--- | Replace the element at the give position and return the old element.
-exchange :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> a -> m a
-{-# INLINE exchange #-}
-exchange v i x = BOUNDS_CHECK(checkIndex) "exchange" i (length v)
-               $ unsafeExchange v i x
-
--- | Yield the element at the given position. No bounds checks are performed.
-unsafeRead :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> m a
-{-# INLINE unsafeRead #-}
-unsafeRead v i = UNSAFE_CHECK(checkIndex) "unsafeRead" i (length v)
-               $ basicUnsafeRead v i
-
--- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite :: (PrimMonad m, MVector v a)
-                                => v (PrimState m) a -> Int -> a -> m ()
-{-# INLINE unsafeWrite #-}
-unsafeWrite v i x = UNSAFE_CHECK(checkIndex) "unsafeWrite" i (length v)
-                  $ basicUnsafeWrite v i x
-
--- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap :: (PrimMonad m, MVector v a)
-                => v (PrimState m) a -> Int -> Int -> m ()
-{-# INLINE unsafeSwap #-}
-unsafeSwap v i j = UNSAFE_CHECK(checkIndex) "unsafeSwap" i (length v)
-                 $ UNSAFE_CHECK(checkIndex) "unsafeSwap" j (length v)
-                 $ do
-                     x <- unsafeRead v i
-                     y <- unsafeRead v j
-                     unsafeWrite v i y
-                     unsafeWrite v j x
-
--- | Replace the element at the give position and return the old element. No
--- bounds checks are performed.
-unsafeExchange :: (PrimMonad m, MVector v a)
-                                => v (PrimState m) a -> Int -> a -> m a
-{-# INLINE unsafeExchange #-}
-unsafeExchange v i x = UNSAFE_CHECK(checkIndex) "unsafeExchange" i (length v)
-                     $ do
-                         y <- unsafeRead v i
-                         unsafeWrite v i x
-                         return y
-
--- Subvectors
--- ----------
+-- Extracting subvectors
+-- ---------------------
 
 -- | Yield a part of the mutable vector without copying it.
 slice :: MVector v a => Int -> Int -> v s a -> v s a
@@ -493,8 +445,16 @@ unsafeDrop :: MVector v a => Int -> v s a -> v s a
 {-# INLINE unsafeDrop #-}
 unsafeDrop n v = unsafeSlice n (length v - n) v
 
--- Construction
--- ------------
+-- Overlapping
+-- -----------
+
+-- Check whether two vectors overlap.
+overlaps :: MVector v a => v s a -> v s a -> Bool
+{-# INLINE overlaps #-}
+overlaps = basicOverlaps
+
+-- Initialisation
+-- --------------
 
 -- | Create a mutable vector of the given length.
 new :: (PrimMonad m, MVector v a) => Int -> m (v (PrimState m) a)
@@ -514,18 +474,6 @@ replicate :: (PrimMonad m, MVector v a) => Int -> a -> m (v (PrimState m) a)
 {-# INLINE replicate #-}
 replicate n x = basicUnsafeReplicate (delay_inline max 0 n) x
 
--- | /DEPRECATED/ Use 'replicate' instead
-newWith :: (PrimMonad m, MVector v a) => Int -> a -> m (v (PrimState m) a)
-{-# INLINE newWith #-}
-newWith = replicate
-
--- | /DEPRECATED/ Use 'replicate' instead
-unsafeNewWith :: (PrimMonad m, MVector v a) => Int -> a -> m (v (PrimState m) a)
-{-# INLINE unsafeNewWith #-}
-unsafeNewWith = replicate
-
-{-# DEPRECATED newWith, unsafeNewWith "Use replicate instead" #-}
-
 -- Growing
 -- -------
 
@@ -578,8 +526,8 @@ unsafeGrowFront v by = UNSAFE_CHECK(checkLength) "unsafeGrowFront" by
                          basicUnsafeCopy (basicUnsafeSlice by n v') v
                          return v'
 
--- Block operations
--- ----------------
+-- Restricting memory usage
+-- ------------------------
 
 -- | Reset all elements of the vector to some undefined value, clearing all
 -- references to external objects. This is usually a noop for unboxed vectors. 
@@ -587,6 +535,73 @@ clear :: (PrimMonad m, MVector v a) => v (PrimState m) a -> m ()
 {-# INLINE clear #-}
 clear = basicClear
 
+-- Accessing individual elements
+-- -----------------------------
+
+-- | Yield the element at the given position.
+read :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> m a
+{-# INLINE read #-}
+read v i = BOUNDS_CHECK(checkIndex) "read" i (length v)
+         $ unsafeRead v i
+
+-- | Replace the element at the given position.
+write :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> a -> m ()
+{-# INLINE write #-}
+write v i x = BOUNDS_CHECK(checkIndex) "write" i (length v)
+            $ unsafeWrite v i x
+
+-- | Swap the elements at the given positions.
+swap :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> Int -> m ()
+{-# INLINE swap #-}
+swap v i j = BOUNDS_CHECK(checkIndex) "swap" i (length v)
+           $ BOUNDS_CHECK(checkIndex) "swap" j (length v)
+           $ unsafeSwap v i j
+
+-- | Replace the element at the give position and return the old element.
+exchange :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> a -> m a
+{-# INLINE exchange #-}
+exchange v i x = BOUNDS_CHECK(checkIndex) "exchange" i (length v)
+               $ unsafeExchange v i x
+
+-- | Yield the element at the given position. No bounds checks are performed.
+unsafeRead :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> m a
+{-# INLINE unsafeRead #-}
+unsafeRead v i = UNSAFE_CHECK(checkIndex) "unsafeRead" i (length v)
+               $ basicUnsafeRead v i
+
+-- | Replace the element at the given position. No bounds checks are performed.
+unsafeWrite :: (PrimMonad m, MVector v a)
+                                => v (PrimState m) a -> Int -> a -> m ()
+{-# INLINE unsafeWrite #-}
+unsafeWrite v i x = UNSAFE_CHECK(checkIndex) "unsafeWrite" i (length v)
+                  $ basicUnsafeWrite v i x
+
+-- | Swap the elements at the given positions. No bounds checks are performed.
+unsafeSwap :: (PrimMonad m, MVector v a)
+                => v (PrimState m) a -> Int -> Int -> m ()
+{-# INLINE unsafeSwap #-}
+unsafeSwap v i j = UNSAFE_CHECK(checkIndex) "unsafeSwap" i (length v)
+                 $ UNSAFE_CHECK(checkIndex) "unsafeSwap" j (length v)
+                 $ do
+                     x <- unsafeRead v i
+                     y <- unsafeRead v j
+                     unsafeWrite v i y
+                     unsafeWrite v j x
+
+-- | Replace the element at the give position and return the old element. No
+-- bounds checks are performed.
+unsafeExchange :: (PrimMonad m, MVector v a)
+                                => v (PrimState m) a -> Int -> a -> m a
+{-# INLINE unsafeExchange #-}
+unsafeExchange v i x = UNSAFE_CHECK(checkIndex) "unsafeExchange" i (length v)
+                     $ do
+                         y <- unsafeRead v i
+                         unsafeWrite v i x
+                         return y
+
+-- Filling and copying
+-- -------------------
+
 -- | Set all elements of the vector to the given value.
 set :: (PrimMonad m, MVector v a) => v (PrimState m) a -> a -> m ()
 {-# INLINE set #-}
@@ -785,3 +800,18 @@ partitionUnknown f s
                       v2' <- unsafeAppend1 v2 i2 x
                       return (v1, i1, v2', i2+1)
 
+-- Deprecated functions
+-- --------------------
+
+-- | /DEPRECATED/ Use 'replicate' instead
+newWith :: (PrimMonad m, MVector v a) => Int -> a -> m (v (PrimState m) a)
+{-# INLINE newWith #-}
+newWith = replicate
+
+-- | /DEPRECATED/ Use 'replicate' instead
+unsafeNewWith :: (PrimMonad m, MVector v a) => Int -> a -> m (v (PrimState m) a)
+{-# INLINE unsafeNewWith #-}
+unsafeNewWith = replicate
+
+{-# DEPRECATED newWith, unsafeNewWith "Use replicate instead" #-}
+
index 6498a5e..5b03f76 100644 (file)
@@ -16,13 +16,37 @@ module Data.Vector.Mutable (
   -- * Mutable boxed vectors
   MVector(..), IOVector, STVector,
 
-  -- * Operations on mutable vectors
-  length, overlaps, slice, new, replicate, read, write, swap,
-  clear, set, copy, grow,
+  -- * Accessors
 
-  -- * Unsafe operations
-  unsafeSlice, unsafeNew, unsafeRead, unsafeWrite,
-  unsafeCopy, unsafeGrow,
+  -- ** Length information
+  length, null,
+
+  -- ** Extracting subvectors
+  slice, init, tail, take, drop,
+  unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,
+
+  -- ** Overlapping
+  overlaps,
+
+  -- * Construction
+
+  -- ** Initialisation
+  new, unsafeNew, replicate,
+
+  -- ** Growing
+  grow, unsafeGrow,
+
+  -- ** Restricting memory usage
+  clear,
+
+  -- * Accessing individual elements
+  read, write, swap,
+  unsafeRead, unsafeWrite, unsafeSwap,
+
+  -- * Modifying vectors
+
+  -- ** Filling and copying
+  set, copy, unsafeCopy,
 
   -- * Deprecated operations
   newWith, unsafeNewWith
@@ -32,7 +56,8 @@ import qualified Data.Vector.Generic.Mutable as G
 import           Data.Primitive.Array
 import           Control.Monad.Primitive
 
-import Prelude hiding ( length, replicate, read )
+import Prelude hiding ( length, null, replicate, reverse, map, read,
+                        take, drop, init, tail )
 
 import Data.Typeable ( Typeable )
 
@@ -85,6 +110,42 @@ instance G.MVector MVector a where
 uninitialised :: a
 uninitialised = error "Data.Vector.Mutable: uninitialised element"
 
+-- Length information
+-- ------------------
+
+-- | Length of the mutable vector.
+length :: MVector s a -> Int
+{-# INLINE length #-}
+length = G.length
+
+-- | Check whether the vector is empty
+null :: MVector s a -> Bool
+{-# INLINE null #-}
+null = G.null
+
+-- Extracting subvectors
+-- ---------------------
+
+-- | Yield a part of the mutable vector without copying it.
+slice :: Int -> Int -> MVector s a -> MVector s a
+{-# INLINE slice #-}
+slice = G.slice
+
+take :: Int -> MVector s a -> MVector s a
+{-# INLINE take #-}
+take = G.take
+
+drop :: Int -> MVector s a -> MVector s a
+{-# INLINE drop #-}
+drop = G.drop
+
+init :: MVector s a -> MVector s a
+{-# INLINE init #-}
+init = G.init
+
+tail :: MVector s a -> MVector s a
+{-# INLINE tail #-}
+tail = G.tail
 
 -- | Yield a part of the mutable vector without copying it. No bounds checks
 -- are performed.
@@ -95,67 +156,78 @@ unsafeSlice :: Int  -- ^ starting index
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
--- | Create a mutable vector of the given length. The length is not checked.
-unsafeNew :: PrimMonad m => Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeNew #-}
-unsafeNew = G.unsafeNew
+unsafeTake :: Int -> MVector s a -> MVector s a
+{-# INLINE unsafeTake #-}
+unsafeTake = G.unsafeTake
 
--- | Yield the element at the given position. No bounds checks are performed.
-unsafeRead :: PrimMonad m => MVector (PrimState m) a -> Int -> m a
-{-# INLINE unsafeRead #-}
-unsafeRead = G.unsafeRead
+unsafeDrop :: Int -> MVector s a -> MVector s a
+{-# INLINE unsafeDrop #-}
+unsafeDrop = G.unsafeDrop
 
--- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite :: PrimMonad m => MVector (PrimState m) a -> Int -> a -> m ()
-{-# INLINE unsafeWrite #-}
-unsafeWrite = G.unsafeWrite
+unsafeInit :: MVector s a -> MVector s a
+{-# INLINE unsafeInit #-}
+unsafeInit = G.unsafeInit
 
--- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap :: PrimMonad m => MVector (PrimState m) a -> Int -> Int -> m ()
-{-# INLINE unsafeSwap #-}
-unsafeSwap = G.unsafeSwap
+unsafeTail :: MVector s a -> MVector s a
+{-# INLINE unsafeTail #-}
+unsafeTail = G.unsafeTail
 
--- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
-unsafeCopy :: PrimMonad m => MVector (PrimState m) a   -- ^ target
-                          -> MVector (PrimState m) a   -- ^ source
-                          -> m ()
-{-# INLINE unsafeCopy #-}
-unsafeCopy = G.unsafeCopy
-
--- | Grow a vector by the given number of elements. The number must be
--- positive but this is not checked.
-unsafeGrow :: PrimMonad m
-               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeGrow #-}
-unsafeGrow = G.unsafeGrow
-
--- | Length of the mutable vector.
-length :: MVector s a -> Int
-{-# INLINE length #-}
-length = G.length
+-- Overlapping
+-- -----------
 
 -- Check whether two vectors overlap.
 overlaps :: MVector s a -> MVector s a -> Bool
 {-# INLINE overlaps #-}
 overlaps = G.overlaps
 
--- | Yield a part of the mutable vector without copying it.
-slice :: Int -> Int -> MVector s a -> MVector s a
-{-# INLINE slice #-}
-slice = G.slice
+-- Initialisation
+-- --------------
 
 -- | Create a mutable vector of the given length.
 new :: PrimMonad m => Int -> m (MVector (PrimState m) a)
 {-# INLINE new #-}
 new = G.new
 
+-- | Create a mutable vector of the given length. The length is not checked.
+unsafeNew :: PrimMonad m => Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeNew #-}
+unsafeNew = G.unsafeNew
+
 -- | Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with an initial value.
 replicate :: PrimMonad m => Int -> a -> m (MVector (PrimState m) a)
 {-# INLINE replicate #-}
 replicate = G.replicate
 
+-- Growing
+-- -------
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive.
+grow :: PrimMonad m
+              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE grow #-}
+grow = G.grow
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive but this is not checked.
+unsafeGrow :: PrimMonad m
+               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeGrow #-}
+unsafeGrow = G.unsafeGrow
+
+-- Restricting memory usage
+-- ------------------------
+
+-- | Reset all elements of the vector to some undefined value, clearing all
+-- references to external objects. This is usually a noop for unboxed vectors. 
+clear :: PrimMonad m => MVector (PrimState m) a -> m ()
+{-# INLINE clear #-}
+clear = G.clear
+
+-- Accessing individual elements
+-- -----------------------------
+
 -- | Yield the element at the given position.
 read :: PrimMonad m => MVector (PrimState m) a -> Int -> m a
 {-# INLINE read #-}
@@ -171,11 +243,24 @@ swap :: PrimMonad m => MVector (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE swap #-}
 swap = G.swap
 
--- | Reset all elements of the vector to some undefined value, clearing all
--- references to external objects. This is usually a noop for unboxed vectors. 
-clear :: PrimMonad m => MVector (PrimState m) a -> m ()
-{-# INLINE clear #-}
-clear = G.clear
+
+-- | Yield the element at the given position. No bounds checks are performed.
+unsafeRead :: PrimMonad m => MVector (PrimState m) a -> Int -> m a
+{-# INLINE unsafeRead #-}
+unsafeRead = G.unsafeRead
+
+-- | Replace the element at the given position. No bounds checks are performed.
+unsafeWrite :: PrimMonad m => MVector (PrimState m) a -> Int -> a -> m ()
+{-# INLINE unsafeWrite #-}
+unsafeWrite = G.unsafeWrite
+
+-- | Swap the elements at the given positions. No bounds checks are performed.
+unsafeSwap :: PrimMonad m => MVector (PrimState m) a -> Int -> Int -> m ()
+{-# INLINE unsafeSwap #-}
+unsafeSwap = G.unsafeSwap
+
+-- Filling and copying
+-- -------------------
 
 -- | Set all elements of the vector to the given value.
 set :: PrimMonad m => MVector (PrimState m) a -> a -> m ()
@@ -189,13 +274,16 @@ copy :: PrimMonad m
 {-# INLINE copy #-}
 copy = G.copy
 
--- | Grow a vector by the given number of elements. The number must be
--- positive.
-grow :: PrimMonad m
-              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE grow #-}
-grow = G.grow
+-- | Copy a vector. The two vectors must have the same length and may not
+-- overlap. This is not checked.
+unsafeCopy :: PrimMonad m => MVector (PrimState m) a   -- ^ target
+                          -> MVector (PrimState m) a   -- ^ source
+                          -> m ()
+{-# INLINE unsafeCopy #-}
+unsafeCopy = G.unsafeCopy
 
+-- Deprecated functions
+-- --------------------
 
 -- | /DEPRECATED/ Use 'replicate' instead
 newWith :: PrimMonad m => Int -> a -> m (MVector (PrimState m) a)
index e804fb3..02af272 100644 (file)
@@ -16,13 +16,37 @@ module Data.Vector.Primitive.Mutable (
   -- * Mutable vectors of primitive types
   MVector(..), IOVector, STVector, Prim,
 
-  -- * Operations on mutable vectors
-  length, overlaps, slice, new, replicate, read, write, swap,
-  clear, set, copy, grow,
+  -- * Accessors
 
-  -- * Unsafe operations
-  unsafeSlice, unsafeNew, unsafeRead, unsafeWrite, unsafeSwap,
-  unsafeCopy, unsafeGrow,
+  -- ** Length information
+  length, null,
+
+  -- ** Extracting subvectors
+  slice, init, tail, take, drop,
+  unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,
+
+  -- ** Overlapping
+  overlaps,
+
+  -- * Construction
+
+  -- ** Initialisation
+  new, unsafeNew, replicate,
+
+  -- ** Growing
+  grow, unsafeGrow,
+
+  -- ** Restricting memory usage
+  clear,
+
+  -- * Accessing individual elements
+  read, write, swap,
+  unsafeRead, unsafeWrite, unsafeSwap,
+
+  -- * Modifying vectors
+
+  -- ** Filling and copying
+  set, copy, unsafeCopy,
 
   -- * Deprecated operations
   newWith, unsafeNewWith
@@ -34,7 +58,8 @@ import           Data.Primitive ( Prim, sizeOf )
 import           Control.Monad.Primitive
 import           Control.Monad ( liftM )
 
-import Prelude hiding( length, replicate, read )
+import Prelude hiding ( length, null, replicate, reverse, map, read,
+                        take, drop, init, tail )
 
 import Data.Typeable ( Typeable )
 
@@ -77,79 +102,125 @@ instance Prim a => G.MVector MVector a where
     where
       sz = sizeOf (undefined :: a)
 
+-- Length information
+-- ------------------
+
+-- | Length of the mutable vector.
+length :: Prim a => MVector s a -> Int
+{-# INLINE length #-}
+length = G.length
+
+-- | Check whether the vector is empty
+null :: Prim a => MVector s a -> Bool
+{-# INLINE null #-}
+null = G.null
+
+-- Extracting subvectors
+-- ---------------------
+
+-- | Yield a part of the mutable vector without copying it.
+slice :: Prim a => Int -> Int -> MVector s a -> MVector s a
+{-# INLINE slice #-}
+slice = G.slice
+
+take :: Prim a => Int -> MVector s a -> MVector s a
+{-# INLINE take #-}
+take = G.take
+
+drop :: Prim a => Int -> MVector s a -> MVector s a
+{-# INLINE drop #-}
+drop = G.drop
+
+init :: Prim a => MVector s a -> MVector s a
+{-# INLINE init #-}
+init = G.init
+
+tail :: Prim a => MVector s a -> MVector s a
+{-# INLINE tail #-}
+tail = G.tail
+
 -- | Yield a part of the mutable vector without copying it. No bounds checks
 -- are performed.
-unsafeSlice :: Prim a => Int  -- ^ starting index
-                      -> Int  -- ^ length of the slice
-                      -> MVector s a   
-                      -> MVector s a
+unsafeSlice :: Prim a
+            => Int  -- ^ starting index
+            -> Int  -- ^ length of the slice
+            -> MVector s a
+            -> MVector s a
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
+unsafeTake :: Prim a => Int -> MVector s a -> MVector s a
+{-# INLINE unsafeTake #-}
+unsafeTake = G.unsafeTake
 
--- | Create a mutable vector of the given length. The length is not checked.
-unsafeNew :: (PrimMonad m, Prim a) => Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeNew #-}
-unsafeNew = G.unsafeNew
-
--- | Yield the element at the given position. No bounds checks are performed.
-unsafeRead :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> m a
-{-# INLINE unsafeRead #-}
-unsafeRead = G.unsafeRead
-
--- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite :: (PrimMonad m, Prim a)
-                                => MVector (PrimState m) a -> Int -> a -> m ()
-{-# INLINE unsafeWrite #-}
-unsafeWrite = G.unsafeWrite
+unsafeDrop :: Prim a => Int -> MVector s a -> MVector s a
+{-# INLINE unsafeDrop #-}
+unsafeDrop = G.unsafeDrop
 
--- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap :: (PrimMonad m, Prim a)
-                => MVector (PrimState m) a -> Int -> Int -> m ()
-{-# INLINE unsafeSwap #-}
-unsafeSwap = G.unsafeSwap
+unsafeInit :: Prim a => MVector s a -> MVector s a
+{-# INLINE unsafeInit #-}
+unsafeInit = G.unsafeInit
 
--- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
-unsafeCopy :: (PrimMonad m, Prim a) => MVector (PrimState m) a   -- ^ target
-                                    -> MVector (PrimState m) a   -- ^ source
-                                    -> m ()
-{-# INLINE unsafeCopy #-}
-unsafeCopy = G.unsafeCopy
-
--- | Grow a vector by the given number of elements. The number must be
--- positive but this is not checked.
-unsafeGrow :: (PrimMonad m, Prim a)
-               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeGrow #-}
-unsafeGrow = G.unsafeGrow
+unsafeTail :: Prim a => MVector s a -> MVector s a
+{-# INLINE unsafeTail #-}
+unsafeTail = G.unsafeTail
 
--- | Length of the mutable vector.
-length :: Prim a => MVector s a -> Int
-{-# INLINE length #-}
-length = G.length
+-- Overlapping
+-- -----------
 
 -- Check whether two vectors overlap.
 overlaps :: Prim a => MVector s a -> MVector s a -> Bool
 {-# INLINE overlaps #-}
 overlaps = G.overlaps
 
--- | Yield a part of the mutable vector without copying it.
-slice :: Prim a => Int -> Int -> MVector s a -> MVector s a
-{-# INLINE slice #-}
-slice = G.slice
+-- Initialisation
+-- --------------
 
 -- | Create a mutable vector of the given length.
 new :: (PrimMonad m, Prim a) => Int -> m (MVector (PrimState m) a)
 {-# INLINE new #-}
 new = G.new
 
+-- | Create a mutable vector of the given length. The length is not checked.
+unsafeNew :: (PrimMonad m, Prim a) => Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeNew #-}
+unsafeNew = G.unsafeNew
+
 -- | Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with an initial value.
 replicate :: (PrimMonad m, Prim a) => Int -> a -> m (MVector (PrimState m) a)
 {-# INLINE replicate #-}
 replicate = G.replicate
 
+-- Growing
+-- -------
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive.
+grow :: (PrimMonad m, Prim a)  
+              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE grow #-}
+grow = G.grow
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive but this is not checked.
+unsafeGrow :: (PrimMonad m, Prim a)
+               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeGrow #-}
+unsafeGrow = G.unsafeGrow
+
+-- Restricting memory usage
+-- ------------------------
+
+-- | Reset all elements of the vector to some undefined value, clearing all
+-- references to external objects. This is usually a noop for unboxed vectors. 
+clear :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> m ()
+{-# INLINE clear #-}
+clear = G.clear
+
+-- Accessing individual elements
+-- -----------------------------
+
 -- | Yield the element at the given position.
 read :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> m a
 {-# INLINE read #-}
@@ -161,16 +232,30 @@ write :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> a -> m ()
 write = G.write
 
 -- | Swap the elements at the given positions.
-swap :: (PrimMonad m, Prim a)
-                => MVector (PrimState m) a -> Int -> Int -> m ()
+swap :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE swap #-}
 swap = G.swap
 
--- | Reset all elements of the vector to some undefined value, clearing all
--- references to external objects. This is usually a noop for unboxed vectors. 
-clear :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> m ()
-{-# INLINE clear #-}
-clear = G.clear
+
+-- | Yield the element at the given position. No bounds checks are performed.
+unsafeRead :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> m a
+{-# INLINE unsafeRead #-}
+unsafeRead = G.unsafeRead
+
+-- | Replace the element at the given position. No bounds checks are performed.
+unsafeWrite
+    :: (PrimMonad m, Prim a) =>  MVector (PrimState m) a -> Int -> a -> m ()
+{-# INLINE unsafeWrite #-}
+unsafeWrite = G.unsafeWrite
+
+-- | Swap the elements at the given positions. No bounds checks are performed.
+unsafeSwap
+    :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> Int -> m ()
+{-# INLINE unsafeSwap #-}
+unsafeSwap = G.unsafeSwap
+
+-- Filling and copying
+-- -------------------
 
 -- | Set all elements of the vector to the given value.
 set :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> a -> m ()
@@ -179,18 +264,22 @@ set = G.set
 
 -- | Copy a vector. The two vectors must have the same length and may not
 -- overlap.
-copy :: (PrimMonad m, Prim a)
-                => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
+copy :: (PrimMonad m, Prim a) 
+                 => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
 {-# INLINE copy #-}
 copy = G.copy
 
--- | Grow a vector by the given number of elements. The number must be
--- positive.
-grow :: (PrimMonad m, Prim a)
-              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE grow #-}
-grow = G.grow
+-- | Copy a vector. The two vectors must have the same length and may not
+-- overlap. This is not checked.
+unsafeCopy :: (PrimMonad m, Prim a)
+           => MVector (PrimState m) a   -- ^ target
+           -> MVector (PrimState m) a   -- ^ source
+           -> m ()
+{-# INLINE unsafeCopy #-}
+unsafeCopy = G.unsafeCopy
 
+-- Deprecated functions
+-- --------------------
 
 -- | /DEPRECATED/ Use 'replicate' instead
 newWith :: (PrimMonad m, Prim a) => Int -> a -> m (MVector (PrimState m) a)
index fa1f4f7..de15eb3 100644 (file)
@@ -16,15 +16,39 @@ module Data.Vector.Storable.Mutable(
   -- * Mutable vectors of 'Storable' types
   MVector(..), IOVector, STVector, Storable,
 
-  -- * Operations on mutable vectors
-  length, overlaps, slice, new, replicate, read, write, swap,
-  clear, set, copy, grow,
+  -- * Accessors
 
-  -- * Unsafe operations
-  unsafeSlice, unsafeNew, unsafeRead, unsafeWrite, unsafeSwap,
-  unsafeCopy, unsafeGrow,
+  -- ** Length information
+  length, null,
 
-  -- * Accessing the underlying memory
+  -- ** Extracting subvectors
+  slice, init, tail, take, drop,
+  unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,
+
+  -- ** Overlapping
+  overlaps,
+
+  -- * Construction
+
+  -- ** Initialisation
+  new, unsafeNew, replicate,
+
+  -- ** Growing
+  grow, unsafeGrow,
+
+  -- ** Restricting memory usage
+  clear,
+
+  -- * Accessing individual elements
+  read, write, swap,
+  unsafeRead, unsafeWrite, unsafeSwap,
+
+  -- * Modifying vectors
+
+  -- ** Filling and copying
+  set, copy, unsafeCopy,
+
+  -- * Raw pointers
   unsafeFromForeignPtr, unsafeToForeignPtr, unsafeWith,
 
   -- * Deprecated operations
@@ -42,7 +66,8 @@ import Foreign.C.Types ( CInt )
 
 import Control.Monad.Primitive
 
-import Prelude hiding( length, replicate, read )
+import Prelude hiding ( length, null, replicate, reverse, map, read,
+                        take, drop, init, tail )
 
 import Data.Typeable ( Typeable )
 
@@ -95,127 +120,162 @@ instance Storable a => G.MVector MVector a where
       withForeignPtr fq $ \_ ->
       copyArray p q n
 
--- | Create a mutable vector from a 'ForeignPtr' with an offset and a length.
--- Modifying data through the 'ForeignPtr' afterwards is unsafe if the vector
--- could have been frozen before the modification.
-unsafeFromForeignPtr :: Storable a
-                     => ForeignPtr a    -- ^ pointer
-                     -> Int             -- ^ offset
-                     -> Int             -- ^ length
-                     -> MVector s a
-{-# INLINE unsafeFromForeignPtr #-}
-unsafeFromForeignPtr fp i n = MVector (offsetToPtr fp i) n fp
+-- Length information
+-- ------------------
 
--- | Yield the underlying 'ForeignPtr' together with the offset to the data
--- and its length. Modifying the data through the 'ForeignPtr' is
--- unsafe if the vector could have frozen before the modification.
-unsafeToForeignPtr :: Storable a => MVector s a -> (ForeignPtr a, Int, Int)
-{-# INLINE unsafeToForeignPtr #-}
-unsafeToForeignPtr (MVector p n fp) = (fp, ptrToOffset fp p, n)
+-- | Length of the mutable vector.
+length :: Storable a => MVector s a -> Int
+{-# INLINE length #-}
+length = G.length
 
--- | Pass a pointer to the vector's data to the IO action. Modifying data
--- through the pointer is unsafe if the vector could have been frozen before
--- the modification.
-unsafeWith :: Storable a => IOVector a -> (Ptr a -> IO b) -> IO b
-{-# INLINE unsafeWith #-}
-unsafeWith (MVector p n fp) m = withForeignPtr fp $ \_ -> m p
+-- | Check whether the vector is empty
+null :: Storable a => MVector s a -> Bool
+{-# INLINE null #-}
+null = G.null
+
+-- Extracting subvectors
+-- ---------------------
+
+-- | Yield a part of the mutable vector without copying it.
+slice :: Storable a => Int -> Int -> MVector s a -> MVector s a
+{-# INLINE slice #-}
+slice = G.slice
+
+take :: Storable a => Int -> MVector s a -> MVector s a
+{-# INLINE take #-}
+take = G.take
+
+drop :: Storable a => Int -> MVector s a -> MVector s a
+{-# INLINE drop #-}
+drop = G.drop
+
+init :: Storable a => MVector s a -> MVector s a
+{-# INLINE init #-}
+init = G.init
+
+tail :: Storable a => MVector s a -> MVector s a
+{-# INLINE tail #-}
+tail = G.tail
 
 -- | Yield a part of the mutable vector without copying it. No bounds checks
 -- are performed.
-unsafeSlice :: Storable a => Int  -- ^ starting index
-                          -> Int  -- ^ length of the slice
-                          -> MVector s a
-                          -> MVector s a
+unsafeSlice :: Storable a
+            => Int  -- ^ starting index
+            -> Int  -- ^ length of the slice
+            -> MVector s a
+            -> MVector s a
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
--- | Create a mutable vector of the given length. The length is not checked.
-unsafeNew :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeNew #-}
-unsafeNew = G.unsafeNew
-
--- | Yield the element at the given position. No bounds checks are performed.
-unsafeRead :: (PrimMonad m, Storable a)
-                                => MVector (PrimState m) a -> Int -> m a
-{-# INLINE unsafeRead #-}
-unsafeRead = G.unsafeRead
-
--- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite :: (PrimMonad m, Storable a)
-                                => MVector (PrimState m) a -> Int -> a -> m ()
-{-# INLINE unsafeWrite #-}
-unsafeWrite = G.unsafeWrite
+unsafeTake :: Storable a => Int -> MVector s a -> MVector s a
+{-# INLINE unsafeTake #-}
+unsafeTake = G.unsafeTake
 
--- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap :: (PrimMonad m, Storable a)
-                => MVector (PrimState m) a -> Int -> Int -> m ()
-{-# INLINE unsafeSwap #-}
-unsafeSwap = G.unsafeSwap
+unsafeDrop :: Storable a => Int -> MVector s a -> MVector s a
+{-# INLINE unsafeDrop #-}
+unsafeDrop = G.unsafeDrop
 
--- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
-unsafeCopy :: (PrimMonad m, Storable a)
-                                => MVector (PrimState m) a   -- ^ target
-                                -> MVector (PrimState m) a   -- ^ source
-                                -> m ()
-{-# INLINE unsafeCopy #-}
-unsafeCopy = G.unsafeCopy
+unsafeInit :: Storable a => MVector s a -> MVector s a
+{-# INLINE unsafeInit #-}
+unsafeInit = G.unsafeInit
 
--- | Grow a vector by the given number of elements. The number must be
--- positive but this is not checked.
-unsafeGrow :: (PrimMonad m, Storable a)
-               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeGrow #-}
-unsafeGrow = G.unsafeGrow
+unsafeTail :: Storable a => MVector s a -> MVector s a
+{-# INLINE unsafeTail #-}
+unsafeTail = G.unsafeTail
 
--- | Length of the mutable vector.
-length :: Storable a => MVector s a -> Int
-{-# INLINE length #-}
-length = G.length
+-- Overlapping
+-- -----------
 
 -- Check whether two vectors overlap.
 overlaps :: Storable a => MVector s a -> MVector s a -> Bool
 {-# INLINE overlaps #-}
 overlaps = G.overlaps
 
--- | Yield a part of the mutable vector without copying it.
-slice :: Storable a => Int -> Int -> MVector s a -> MVector s a
-{-# INLINE slice #-}
-slice = G.slice
+-- Initialisation
+-- --------------
 
 -- | Create a mutable vector of the given length.
 new :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
 {-# INLINE new #-}
 new = G.new
 
+-- | Create a mutable vector of the given length. The length is not checked.
+unsafeNew :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeNew #-}
+unsafeNew = G.unsafeNew
+
 -- | Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with an initial value.
 replicate :: (PrimMonad m, Storable a) => Int -> a -> m (MVector (PrimState m) a)
 {-# INLINE replicate #-}
 replicate = G.replicate
 
+-- Growing
+-- -------
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive.
+grow :: (PrimMonad m, Storable a)  
+              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE grow #-}
+grow = G.grow
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive but this is not checked.
+unsafeGrow :: (PrimMonad m, Storable a)
+               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeGrow #-}
+unsafeGrow = G.unsafeGrow
+
+-- Restricting memory usage
+-- ------------------------
+
+-- | Reset all elements of the vector to some undefined value, clearing all
+-- references to external objects. This is usually a noop for unboxed vectors. 
+clear :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> m ()
+{-# INLINE clear #-}
+clear = G.clear
+
+-- Accessing individual elements
+-- -----------------------------
+
 -- | Yield the element at the given position.
 read :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m a
 {-# INLINE read #-}
 read = G.read
 
 -- | Replace the element at the given position.
-write :: (PrimMonad m, Storable a)
-                                => MVector (PrimState m) a -> Int -> a -> m ()
+write
+    :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m ()
 {-# INLINE write #-}
 write = G.write
 
 -- | Swap the elements at the given positions.
-swap :: (PrimMonad m, Storable a)
-                => MVector (PrimState m) a -> Int -> Int -> m ()
+swap
+    :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE swap #-}
 swap = G.swap
 
--- | Reset all elements of the vector to some undefined value, clearing all
--- references to external objects. This is usually a noop for unboxed vectors. 
-clear :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> m ()
-{-# INLINE clear #-}
-clear = G.clear
+
+-- | Yield the element at the given position. No bounds checks are performed.
+unsafeRead :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m a
+{-# INLINE unsafeRead #-}
+unsafeRead = G.unsafeRead
+
+-- | Replace the element at the given position. No bounds checks are performed.
+unsafeWrite
+    :: (PrimMonad m, Storable a) =>  MVector (PrimState m) a -> Int -> a -> m ()
+{-# INLINE unsafeWrite #-}
+unsafeWrite = G.unsafeWrite
+
+-- | Swap the elements at the given positions. No bounds checks are performed.
+unsafeSwap
+    :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
+{-# INLINE unsafeSwap #-}
+unsafeSwap = G.unsafeSwap
+
+-- Filling and copying
+-- -------------------
 
 -- | Set all elements of the vector to the given value.
 set :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> a -> m ()
@@ -224,18 +284,50 @@ set = G.set
 
 -- | Copy a vector. The two vectors must have the same length and may not
 -- overlap.
-copy :: (PrimMonad m, Storable a)
-                => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
+copy :: (PrimMonad m, Storable a) 
+                 => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
 {-# INLINE copy #-}
 copy = G.copy
 
--- | Grow a vector by the given number of elements. The number must be
--- positive.
-grow :: (PrimMonad m, Storable a)
-              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE grow #-}
-grow = G.grow
+-- | Copy a vector. The two vectors must have the same length and may not
+-- overlap. This is not checked.
+unsafeCopy :: (PrimMonad m, Storable a)
+           => MVector (PrimState m) a   -- ^ target
+           -> MVector (PrimState m) a   -- ^ source
+           -> m ()
+{-# INLINE unsafeCopy #-}
+unsafeCopy = G.unsafeCopy
+
+-- Raw pointers
+-- ------------
+
+-- | Create a mutable vector from a 'ForeignPtr' with an offset and a length.
+-- Modifying data through the 'ForeignPtr' afterwards is unsafe if the vector
+-- could have been frozen before the modification.
+unsafeFromForeignPtr :: Storable a
+                     => ForeignPtr a    -- ^ pointer
+                     -> Int             -- ^ offset
+                     -> Int             -- ^ length
+                     -> MVector s a
+{-# INLINE unsafeFromForeignPtr #-}
+unsafeFromForeignPtr fp i n = MVector (offsetToPtr fp i) n fp
+
+-- | Yield the underlying 'ForeignPtr' together with the offset to the data
+-- and its length. Modifying the data through the 'ForeignPtr' is
+-- unsafe if the vector could have frozen before the modification.
+unsafeToForeignPtr :: Storable a => MVector s a -> (ForeignPtr a, Int, Int)
+{-# INLINE unsafeToForeignPtr #-}
+unsafeToForeignPtr (MVector p n fp) = (fp, ptrToOffset fp p, n)
+
+-- | Pass a pointer to the vector's data to the IO action. Modifying data
+-- through the pointer is unsafe if the vector could have been frozen before
+-- the modification.
+unsafeWith :: Storable a => IOVector a -> (Ptr a -> IO b) -> IO b
+{-# INLINE unsafeWith #-}
+unsafeWith (MVector p n fp) m = withForeignPtr fp $ \_ -> m p
 
+-- Deprecated functions
+-- --------------------
 
 -- | /DEPRECATED/ Use 'replicate' instead
 newWith :: (PrimMonad m, Storable a) => Int -> a -> m (MVector (PrimState m) a)
index fed81cf..96d5d3a 100644 (file)
@@ -14,100 +14,176 @@ module Data.Vector.Unboxed.Mutable (
   -- * Mutable vectors of primitive types
   MVector(..), IOVector, STVector, Unbox,
 
-  -- * Operations on mutable vectors
-  length, overlaps, slice, new, replicate, read, write, swap,
-  clear, set, copy, grow,
+  -- * Accessors
+
+  -- ** Length information
+  length, null,
+
+  -- ** Extracting subvectors
+  slice, init, tail, take, drop,
+  unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,
+
+  -- ** Overlapping
+  overlaps,
+
+  -- * Construction
+
+  -- ** Initialisation
+  new, unsafeNew, replicate,
+
+  -- ** Growing
+  grow, unsafeGrow,
+
+  -- ** Restricting memory usage
+  clear,
+
+  -- * Zipping and unzipping
   zip, zip3, zip4, zip5, zip6,
   unzip, unzip3, unzip4, unzip5, unzip6,
 
-  -- * Unsafe operations
-  unsafeSlice, unsafeNew, unsafeRead, unsafeWrite, unsafeSwap,
-  unsafeCopy, unsafeGrow,
+  -- * Accessing individual elements
+  read, write, swap,
+  unsafeRead, unsafeWrite, unsafeSwap,
+
+  -- * Modifying vectors
+
+  -- ** Filling and copying
+  set, copy, unsafeCopy,
 
   -- * Deprecated operations
   newWith, unsafeNewWith
+
 ) where
 
 import Data.Vector.Unboxed.Base
 import qualified Data.Vector.Generic.Mutable as G
 import Control.Monad.Primitive
 
-import Prelude hiding ( zip, zip3, unzip, unzip3, length, replicate, read )
+import Prelude hiding ( length, null, replicate, reverse, map, read,
+                        take, drop, init, tail,
+                        zip, zip3, unzip, unzip3 )
 
 #include "vector.h"
 
+-- Length information
+-- ------------------
+
+-- | Length of the mutable vector.
+length :: Unbox a => MVector s a -> Int
+{-# INLINE length #-}
+length = G.length
+
+-- | Check whether the vector is empty
+null :: Unbox a => MVector s a -> Bool
+{-# INLINE null #-}
+null = G.null
+
+-- Extracting subvectors
+-- ---------------------
+
+-- | Yield a part of the mutable vector without copying it.
+slice :: Unbox a => Int -> Int -> MVector s a -> MVector s a
+{-# INLINE slice #-}
+slice = G.slice
+
+take :: Unbox a => Int -> MVector s a -> MVector s a
+{-# INLINE take #-}
+take = G.take
+
+drop :: Unbox a => Int -> MVector s a -> MVector s a
+{-# INLINE drop #-}
+drop = G.drop
+
+init :: Unbox a => MVector s a -> MVector s a
+{-# INLINE init #-}
+init = G.init
+
+tail :: Unbox a => MVector s a -> MVector s a
+{-# INLINE tail #-}
+tail = G.tail
+
 -- | Yield a part of the mutable vector without copying it. No bounds checks
 -- are performed.
-unsafeSlice :: Unbox a => Int  -- ^ starting index
-                       -> Int  -- ^ length of the slice
-                       -> MVector s a
-                       -> MVector s a
+unsafeSlice :: Unbox a
+            => Int  -- ^ starting index
+            -> Int  -- ^ length of the slice
+            -> MVector s a
+            -> MVector s a
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
--- | Create a mutable vector of the given length. The length is not checked.
-unsafeNew :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeNew #-}
-unsafeNew = G.unsafeNew
+unsafeTake :: Unbox a => Int -> MVector s a -> MVector s a
+{-# INLINE unsafeTake #-}
+unsafeTake = G.unsafeTake
 
--- | Yield the element at the given position. No bounds checks are performed.
-unsafeRead :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a
-{-# INLINE unsafeRead #-}
-unsafeRead = G.unsafeRead
+unsafeDrop :: Unbox a => Int -> MVector s a -> MVector s a
+{-# INLINE unsafeDrop #-}
+unsafeDrop = G.unsafeDrop
 
--- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite :: (PrimMonad m, Unbox a)
-                                => MVector (PrimState m) a -> Int -> a -> m ()
-{-# INLINE unsafeWrite #-}
-unsafeWrite = G.unsafeWrite
+unsafeInit :: Unbox a => MVector s a -> MVector s a
+{-# INLINE unsafeInit #-}
+unsafeInit = G.unsafeInit
 
--- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap :: (PrimMonad m, Unbox a)
-                => MVector (PrimState m) a -> Int -> Int -> m ()
-{-# INLINE unsafeSwap #-}
-unsafeSwap = G.unsafeSwap
+unsafeTail :: Unbox a => MVector s a -> MVector s a
+{-# INLINE unsafeTail #-}
+unsafeTail = G.unsafeTail
 
--- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
-unsafeCopy :: (PrimMonad m, Unbox a) => MVector (PrimState m) a   -- ^ target
-                                    -> MVector (PrimState m) a   -- ^ source
-                                    -> m ()
-{-# INLINE unsafeCopy #-}
-unsafeCopy = G.unsafeCopy
-
--- | Grow a vector by the given number of elements. The number must be
--- positive but this is not checked.
-unsafeGrow :: (PrimMonad m, Unbox a)
-               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE unsafeGrow #-}
-unsafeGrow = G.unsafeGrow
-
--- | Length of the mutable vector.
-length :: Unbox a => MVector s a -> Int
-{-# INLINE length #-}
-length = G.length
+-- Overlapping
+-- -----------
 
 -- Check whether two vectors overlap.
 overlaps :: Unbox a => MVector s a -> MVector s a -> Bool
 {-# INLINE overlaps #-}
 overlaps = G.overlaps
 
--- | Yield a part of the mutable vector without copying it.
-slice :: Unbox a => Int -> Int -> MVector s a -> MVector s a
-{-# INLINE slice #-}
-slice = G.slice
+-- Initialisation
+-- --------------
 
 -- | Create a mutable vector of the given length.
 new :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a)
 {-# INLINE new #-}
 new = G.new
 
--- | Create a mutable vector of the given length and fill it with an
--- initial value.
+-- | Create a mutable vector of the given length. The length is not checked.
+unsafeNew :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeNew #-}
+unsafeNew = G.unsafeNew
+
+-- | Create a mutable vector of the given length (0 if the length is negative)
+-- and fill it with an initial value.
 replicate :: (PrimMonad m, Unbox a) => Int -> a -> m (MVector (PrimState m) a)
 {-# INLINE replicate #-}
 replicate = G.replicate
 
+-- Growing
+-- -------
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive.
+grow :: (PrimMonad m, Unbox a)  
+              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE grow #-}
+grow = G.grow
+
+-- | Grow a vector by the given number of elements. The number must be
+-- positive but this is not checked.
+unsafeGrow :: (PrimMonad m, Unbox a)
+               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+{-# INLINE unsafeGrow #-}
+unsafeGrow = G.unsafeGrow
+
+-- Restricting memory usage
+-- ------------------------
+
+-- | Reset all elements of the vector to some undefined value, clearing all
+-- references to external objects. This is usually a noop for unboxed vectors. 
+clear :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> m ()
+{-# INLINE clear #-}
+clear = G.clear
+
+-- Accessing individual elements
+-- -----------------------------
+
 -- | Yield the element at the given position.
 read :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a
 {-# INLINE read #-}
@@ -119,16 +195,30 @@ write :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> a -> m ()
 write = G.write
 
 -- | Swap the elements at the given positions.
-swap :: (PrimMonad m, Unbox a)
-                => MVector (PrimState m) a -> Int -> Int -> m ()
+swap :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE swap #-}
 swap = G.swap
 
--- | Reset all elements of the vector to some undefined value, clearing all
--- references to external objects. This is usually a noop for unboxed vectors. 
-clear :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> m ()
-{-# INLINE clear #-}
-clear = G.clear
+
+-- | Yield the element at the given position. No bounds checks are performed.
+unsafeRead :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a
+{-# INLINE unsafeRead #-}
+unsafeRead = G.unsafeRead
+
+-- | Replace the element at the given position. No bounds checks are performed.
+unsafeWrite
+    :: (PrimMonad m, Unbox a) =>  MVector (PrimState m) a -> Int -> a -> m ()
+{-# INLINE unsafeWrite #-}
+unsafeWrite = G.unsafeWrite
+
+-- | Swap the elements at the given positions. No bounds checks are performed.
+unsafeSwap
+    :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m ()
+{-# INLINE unsafeSwap #-}
+unsafeSwap = G.unsafeSwap
+
+-- Filling and copying
+-- -------------------
 
 -- | Set all elements of the vector to the given value.
 set :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> a -> m ()
@@ -137,18 +227,22 @@ set = G.set
 
 -- | Copy a vector. The two vectors must have the same length and may not
 -- overlap.
-copy :: (PrimMonad m, Unbox a)
-                => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
+copy :: (PrimMonad m, Unbox a) 
+                 => MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
 {-# INLINE copy #-}
 copy = G.copy
 
--- | Grow a vector by the given number of elements. The number must be
--- positive.
-grow :: (PrimMonad m, Unbox a)
-              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
-{-# INLINE grow #-}
-grow = G.grow
+-- | Copy a vector. The two vectors must have the same length and may not
+-- overlap. This is not checked.
+unsafeCopy :: (PrimMonad m, Unbox a)
+           => MVector (PrimState m) a   -- ^ target
+           -> MVector (PrimState m) a   -- ^ source
+           -> m ()
+{-# INLINE unsafeCopy #-}
+unsafeCopy = G.unsafeCopy
 
+-- Deprecated functions
+-- --------------------
 
 -- | /DEPRECATED/ Use 'replicate' instead
 newWith :: (PrimMonad m, Unbox a) => Int -> a -> m (MVector (PrimState m) a)
@@ -162,7 +256,6 @@ unsafeNewWith = G.replicate
 
 {-# DEPRECATED newWith, unsafeNewWith "Use replicate instead" #-}
 
-
 #define DEFINE_MUTABLE
 #include "unbox-tuple-instances"