[commit: dph] master: Export more PArray functions (51ebeab)

[Ben Lippmeier]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/dph

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/51ebeabc4136b701d9acdc46b097a6e20542563b

>---------------------------------------------------------------

commit 51ebeabc4136b701d9acdc46b097a6e20542563b
Author: Ben Lippmeier <benl at ouroborus.net>
Date:   Mon May 9 14:19:04 2011 +1000

    Export more PArray functions

>---------------------------------------------------------------

 .../Data/Array/Parallel/Lifted/Combinators.hs      |    9 +-
 dph-common/Data/Array/Parallel/PArray.hs           |  137 ++++++++++++++++++--
 2 files changed, 131 insertions(+), 15 deletions(-)

diff --git a/dph-common/Data/Array/Parallel/Lifted/Combinators.hs b/dph-common/Data/Array/Parallel/Lifted/Combinators.hs
index 701336d..30aeadf 100644
--- a/dph-common/Data/Array/Parallel/Lifted/Combinators.hs
+++ b/dph-common/Data/Array/Parallel/Lifted/Combinators.hs
@@ -18,7 +18,8 @@
 --    with applications being performed by the liftedApply function 
 --    from "Data.Array.Parallel.Lifted.Closure"
 --     
---  TODO: combine2PA_l isn't implemented.
+--  TODO: combine2PA_l isn't implemented and will just `error` if you
+--        try to use it. None of our benchmarks do yet...
 --
 module Data.Array.Parallel.Lifted.Combinators (
   lengthPA, replicatePA, singletonPA, mapPA, crossMapPA,
@@ -26,8 +27,10 @@ module Data.Array.Parallel.Lifted.Combinators (
   packPA, filterPA, combine2PA, indexPA, concatPA, appPA, enumFromToPA_Int,
   indexedPA, slicePA, updatePA, bpermutePA,
 
-  lengthPA_v, replicatePA_v, singletonPA_v, zipPA_v, unzipPA_v,
-  indexPA_v, appPA_v, enumFromToPA_v
+  -- * Functions re-exported by Data.Array.Parallel.PArray
+  lengthPA_v, replicatePA_v, singletonPA_v, zipPA_v,    unzipPA_v,
+  packPA_v,   concatPA_v,    indexedPA_v,   updatePA_v, bpermutePA_v,
+  slicePA_v,  indexPA_v,     appPA_v,       enumFromToPA_v
 ) where
 
 import Data.Array.Parallel.Lifted.PArray
diff --git a/dph-common/Data/Array/Parallel/PArray.hs b/dph-common/Data/Array/Parallel/PArray.hs
index 50d677c..6f7e75c 100644
--- a/dph-common/Data/Array/Parallel/PArray.hs
+++ b/dph-common/Data/Array/Parallel/PArray.hs
@@ -45,10 +45,24 @@
 module Data.Array.Parallel.PArray (
   PArray, PA, Random(..),
 
-  length, empty, replicate, singleton, (!:),
-  zip, unzip, enumFromTo, fromList, toList, nf, 
-  fromUArrPA'
-) where
+  -- * Array operators.
+  length,
+  empty,
+  replicate,
+  singleton,
+  (!:),
+  zip, unzip,
+  enumFromTo,
+  
+  -- * Conversion
+  fromList, 
+  toList,
+  fromUArrPA',
+  
+  -- * Evaluation
+  nf
+) 
+where
 import Data.Array.Parallel.Lifted.PArray
 import Data.Array.Parallel.PArray.PReprInstances
 import Data.Array.Parallel.Lifted.Combinators
@@ -61,51 +75,150 @@ import qualified System.Random as R
 
 import Prelude          hiding ( length, replicate, zip, unzip, enumFromTo )
 
-length :: PA a => PArray a -> Int
-{-# INLINE length #-}
-length = lengthPA_v
+-- NOTE: 
+-- Most of these functions just export the corresponding "vectorised" 
+-- function from "Data.Array.Parallel.Lifted.Closure". We don't export
+-- higher-order functions like map and filter because the versions 
+-- from there want closures as their function parameters.
+--
+-- Instead, we should probably move the first-order "vectorised" 
+-- functions from D.A.P.L.Closure into this module, and just define
+-- the higher-order and lifted ones there.
+--
+-- We still want to export these plain PArray functions to make it easier
+-- to convert between vectorised and unvectorised code in benchmarks.
+--
 
+-- | O(1). An empty array, with no elements.
 empty :: PA a => PArray a
 {-# INLINE empty #-}
 empty = emptyPA
 
+
+-- | O(1). Retrieve a numbered element from an array.
+(!:) :: PA a => PArray a -> Int -> a
+{-# INLINE (!:) #-}
+(!:) = indexPA_v
+
+
+-- | O(1). Yield the length of an array.
+length :: PA a => PArray a -> Int
+{-# INLINE length #-}
+length = lengthPA_v
+
+
+-- | O(n). Produce an array containing copies of a given element.
 replicate :: PA a => Int -> a -> PArray a
 {-# INLINE replicate #-}
 replicate = replicatePA_v
 
+
+-- | O(1). Produce an array containing a single element.
 singleton :: PA a => a -> PArray a
 {-# INLINE singleton #-}
 singleton = singletonPA_v
 
-(!:) :: PA a => PArray a -> Int -> a
-{-# INLINE (!:) #-}
-(!:) = indexPA_v
 
+-- | O(1). Takes two arrays and returns an array of corresponding pairs.
+--         If one array is short, excess elements of the longer array are
+--         discarded.
 zip :: (PA a, PA b) => PArray a -> PArray b -> PArray (a,b)
 {-# INLINE zip #-}
 zip = zipPA_v
 
+
+-- | O(1). Transform an array into an array of the first components,
+--         and an array of the second components.
 unzip :: (PA a, PA b) => PArray (a,b) -> (PArray a, PArray b)
 {-# INLINE unzip #-}
 unzip = unzipPA_v
 
+
+-- | Select the elements of an array that have their tag set as True.
+--   
+-- @
+-- packPA [12, 24, 42, 93] [True, False, False, True]
+--  = [24, 42]
+-- @
+pack :: PA a => PArray a -> PArray Bool -> PArray a
+{-# INLINE pack #-}
+pack = packPA_v
+
+
+
+-- | Concatenate an array of arrays into a single array.
+concat :: PA a => PArray (PArray a) -> PArray a
+{-# INLINE concat #-}
+concat = concatPA_v
+
+
+-- | Append two arrays
+(+:+) :: PA a => PArray a -> PArray a -> PArray a
+{-# INLINE (+:+) #-}
+(+:+) = appPA_v
+
+
+-- | O(n). Tag each element of an array with its index.
+--
+--   @indexed [42, 93, 13] = [(0, 42), (1, 93), (2, 13)]@ 
+--
+indexed :: PA a => PArray a -> PArray (Int, a)
+{-# INLINE indexed #-}
+indexed = indexedPA_v
+
+
+-- | Extract a subrange of elements from an array.
+--   The first argument is the starting index, while the second is the 
+--   length of the slice.
+--  
+slice :: PA a => Int -> Int -> PArray a -> PArray a
+{-# INLINE slice #-}
+slice = slicePA_v
+
+
+-- | Copy the source array in the destination, using new values for the given indices.
+update :: PA a => PArray a -> PArray (Int,a) -> PArray a
+{-# INLINE update #-}
+update = updatePA_v
+
+
+-- | O(n). Backwards permutation of array elements.
+--
+--   @bpermute [50, 60, 20, 30] [0, 3, 2]  = [50, 30, 20]@
+--
+bpermute :: PA a => PArray a -> PArray Int -> PArray a
+{-# INLINE bpermute #-}
+bpermute  = bpermutePA_v
+
+
+-- | O(n). Generate a range of @Int at s.
 enumFromTo :: Int -> Int -> PArray Int
 {-# INLINE enumFromTo #-}
 enumFromTo = enumFromToPA_v
 
+
+-- Conversion -----------------------------------------------------------------
+-- | Create a `PArray` from a list.
 fromList :: PA a => [a] -> PArray a
 {-# INLINE fromList #-}
 fromList = fromListPA
 
+-- | Create a list from a `PArray`.
 toList :: PA a => PArray a -> [a]
 toList xs = [indexPA_v xs i | i <- [0 .. length xs - 1]]
 
-nf :: PA a => PArray a -> ()
-nf = nfPA
 
 instance (PA a, Show a) => Show (PArray a) where
   showsPrec n xs = showsApp n "fromList<PArray>" (toList xs)
 
+
+-- Evaluation -----------------------------------------------------------------
+-- | Ensure an array is fully evaluated.
+nf :: PA a => PArray a -> ()
+nf = nfPA
+
+
+-- Randoms --------------------------------------------------------------------
 class Random a where
   randoms  :: R.RandomGen g => Int -> g -> PArray a
   randomRs :: R.RandomGen g => Int -> (a, a) -> g -> PArray a