[project @ 2005-10-13 11:09:50 by ross]

[haskell-directory.git] / Data / Array / Storable.hs

diff --git a/Data/Array/Storable.hs b/Data/Array/Storable.hs
index 39abe70..d10a793 100644 (file)
--- a/Data/Array/Storable.hs
+++ b/Data/Array/Storable.hs
@@ -6,40 +6,37 @@
 -- 
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
--- Portability :  non-portable
+-- Portability :  non-portable (uses Data.Array.MArray)
 --
 -- 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 ()
+    touchStorableArray, -- :: StorableArray i e -> IO ()
+
+    unsafeForeignPtrToStorableArray
     )
     where
 
@@ -49,6 +46,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
@@ -74,8 +72,23 @@ 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
+
+-- |Construct a 'StorableArray' from an arbitrary 'ForeignPtr'.  It is
+-- the caller's responsibility to ensure that the 'ForeignPtr' points to
+-- an area of memory sufficient for the specified bounds.
+unsafeForeignPtrToStorableArray 
+   :: ForeignPtr e -> (i,i) -> IO (StorableArray i e)
+unsafeForeignPtrToStorableArray p (l,u) =
+   return (StorableArray l u p)