[project @ 2005-01-11 16:04:08 by simonmar]

[ghc-base.git] / Data / Array.hs

diff --git a/Data/Array.hs b/Data/Array.hs
index 0dd1b23..e8e8c76 100644 (file)
--- a/Data/Array.hs
+++ b/Data/Array.hs
@@ -1,4 +1,4 @@
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Array 
@@ -11,24 +11,35 @@
 --
 -- Basic non-strict arrays.
 --
+-- /Note:/ The "Data.Array.IArray" module provides more general interface
+-- to immutable arrays: it defines operations with the same names as
+-- those defined below, but with more general types, and also defines
+-- 'Array' instances of the relevant classes.  To use that more general
+-- interface, import "Data.Array.IArray" but not "Data.Array".
 -----------------------------------------------------------------------------
 
 module  Data.Array 
 
     ( 
+    -- * Immutable non-strict arrays
+    -- $intro
       module Data.Ix           -- export all of Ix 
     , Array                    -- Array type is abstract
 
+    -- * Array construction
     , array        -- :: (Ix a) => (a,a) -> [(a,b)] -> Array a b
     , listArray     -- :: (Ix a) => (a,a) -> [b] -> Array a b
+    , accumArray    -- :: (Ix a) => (b -> c -> b) -> b -> (a,a) -> [(a,c)] -> Array a b
+    -- * Accessing arrays
     , (!)           -- :: (Ix a) => Array a b -> a -> b
     , bounds        -- :: (Ix a) => Array a b -> (a,a)
     , indices       -- :: (Ix a) => Array a b -> [a]
     , elems         -- :: (Ix a) => Array a b -> [b]
     , assocs        -- :: (Ix a) => Array a b -> [(a,b)]
-    , accumArray    -- :: (Ix a) => (b -> c -> b) -> b -> (a,a) -> [(a,c)] -> Array a b
+    -- * Incremental array updates
     , (//)          -- :: (Ix a) => Array a b -> [(a,b)] -> Array a b
     , accum         -- :: (Ix a) => (b -> c -> b) -> Array a b -> [(a,c)] -> Array a b
+    -- * Derived arrays
     , ixmap         -- :: (Ix a, Ix b) => (a,a) -> (a -> b) -> Array b c -> Array a b
 
     -- Array instances:
@@ -67,3 +78,16 @@ import Data.Typeable
 #include "Typeable.h"
 INSTANCE_TYPEABLE2(Array,arrayTc,"Array")
 #endif
+
+{- $intro
+Haskell provides indexable /arrays/, which may be thought of as functions
+whose domains are isomorphic to contiguous subsets of the integers.
+Functions restricted in this way can be implemented efficiently;
+in particular, a programmer may reasonably expect rapid access to
+the components.  To ensure the possibility of such an implementation,
+arrays are treated as data, not as general functions.
+
+Since most array functions involve the class 'Ix', this module is exported
+from "Data.Array" so that modules need not import both "Data.Array" and
+"Data.Ix".
+-}