[project @ 2005-04-06 22:05:58 by simonmar]

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

diff --git a/Data/Array/Storable.hs b/Data/Array/Storable.hs
index 76d2dae..d336e34 100644 (file)
--- a/Data/Array/Storable.hs
+++ b/Data/Array/Storable.hs
@@ -1,46 +1,39 @@
 -----------------------------------------------------------------------------
--- 
+-- |
 -- Module      :  Data.Array.Storable
 -- Copyright   :  (c) The University of Glasgow 2001
--- License     :  BSD-style (see the file libraries/core/LICENSE)
+-- License     :  BSD-style (see the file libraries/base/LICENSE)
 -- 
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
 -- Portability :  non-portable
 --
--- $Id: Storable.hs,v 1.2 2001/07/04 10:51:09 simonmar Exp $
---
 -- A storable array is an IO-mutable array which stores its
 -- contents in a contiguous memory block living in the C
--- heap. Elements are stored according to the class Storable.
+-- heap. Elements are stored according to the class 'Storable'.
 -- You can obtain the pointer to the array contents to manipulate
 -- elements from languages like C.
 --
--- It's similar to IOUArray but slower. Its advantage is that
--- it's compatible with C.
+-- It is similar to 'Data.Array.IO.IOUArray' but slower.
+-- Its advantage is that it's compatible with C.
 --
 -----------------------------------------------------------------------------
 
 module Data.Array.Storable (
     
-    -- Array type:
+    -- * Arrays of 'Storable' things.
     StorableArray, -- data StorableArray index element
                    --     -- index type must be in class Ix
                    --     -- element type must be in class Storable
     
-    -- Module MArray provides the interface of storable arrays.
-    -- They are instances of class MArray (with IO monad).
+    -- * Overloaded mutable array interface
+    -- | Module "Data.Array.MArray" provides the interface of storable arrays.
+    -- They are instances of class 'MArray' (with the 'IO' monad).
     module Data.Array.MArray,
     
-    -- The pointer to the array contents is obtained by withStorableArray.
-    -- The idea is similar to ForeignPtr (used internally here). The
-    -- pointer should be used only during execution of the IO action
-    -- retured by the function passed as argument to withStorableArray:
+    -- * Accessing the pointer to the array contents
     withStorableArray, -- :: StorableArray i e -> (Ptr e -> IO a) -> IO a
     
-    -- If you want to use it afterwards, ensure that you
-    -- touchStorableArray after the last use of the pointer,
-    -- so the array is not freed too early:
     touchStorableArray -- :: StorableArray i e -> IO ()
     )
     where
@@ -51,6 +44,7 @@ import Data.Array.Base
 import Data.Array.MArray
 import Foreign hiding (newArray)
 
+-- |The array type
 data StorableArray i e = StorableArray !i !i !(ForeignPtr e)
 
 instance HasBounds StorableArray where
@@ -59,16 +53,15 @@ instance HasBounds StorableArray where
 instance Storable e => MArray StorableArray e IO where
 
     newArray (l,u) init = do
-        a <- mallocArray size
-        sequence_ [pokeElemOff a i init | i <- [0..size-1]]
-        fp <- newForeignPtr a (free a)
+        fp <- mallocForeignPtrArray size
+        withForeignPtr fp $ \a ->
+            sequence_ [pokeElemOff a i init | i <- [0..size-1]]
         return (StorableArray l u fp)
         where
         size = rangeSize (l,u)
 
     newArray_ (l,u) = do
-        a  <- mallocArray (rangeSize (l,u))
-        fp <- newForeignPtr a (free a)
+        fp <- mallocForeignPtrArray (rangeSize (l,u))
         return (StorableArray l u fp)
 
     unsafeRead (StorableArray _ _ fp) i =
@@ -77,8 +70,15 @@ instance Storable e => MArray StorableArray e IO where
     unsafeWrite (StorableArray _ _ fp) i e =
         withForeignPtr fp $ \a -> pokeElemOff a i e
 
+-- |The pointer to the array contents is obtained by 'withStorableArray'.
+-- The idea is similar to 'ForeignPtr' (used internally here).
+-- The pointer should be used only during execution of the 'IO' action
+-- retured by the function passed as argument to 'withStorableArray'.
 withStorableArray :: StorableArray i e -> (Ptr e -> IO a) -> IO a
 withStorableArray (StorableArray _ _ fp) f = withForeignPtr fp f
 
+-- |If you want to use it afterwards, ensure that you
+-- 'touchStorableArray' after the last use of the pointer,
+-- so the array is not freed too early.
 touchStorableArray :: StorableArray i e -> IO ()
 touchStorableArray (StorableArray _ _ fp) = touchForeignPtr fp