[project @ 2004-01-05 17:44:30 by ross]

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

diff --git a/Data/Array/Base.hs b/Data/Array/Base.hs
index e32e8c0..03d604c 100644 (file)
--- a/Data/Array/Base.hs
+++ b/Data/Array/Base.hs
@@ -19,12 +19,10 @@ module Data.Array.Base where
 import Prelude
 
 import Data.Ix         ( Ix, range, index, rangeSize )
-import Data.Bits
 import Data.Int
 import Data.Word
 import Foreign.Ptr
 import Foreign.StablePtr
-import Foreign.Storable
 
 #ifdef __GLASGOW_HASKELL__
 import GHC.Arr         ( STArray, unsafeIndex )
@@ -41,6 +39,8 @@ import GHC.Word               ( Word8(..), Word16(..), Word32(..), Word64(..) )
 #endif
 
 #ifdef __HUGS__
+import Data.Bits
+import Foreign.Storable
 import qualified Hugs.Array as Arr
 import qualified Hugs.ST as ArrST
 import Hugs.Array ( unsafeIndex )
@@ -48,7 +48,7 @@ import Hugs.ST ( STArray, ST(..), runST )
 import Hugs.ByteArray
 #endif
 
-import Data.Dynamic
+import Data.Typeable
 #include "Typeable.h"
 
 #include "MachDeps.h"
@@ -1556,14 +1556,34 @@ freezeSTUArray (STUArray l u marr#) = ST $ \s1# ->
 -- have a reference to the array at the point where you unsafely
 -- freeze it (and, subsequently mutate it, I suspect).
 
-{-# INLINE unsafeFreeze #-}
+{- |
+   Converts an mutable array into an immutable array.  The 
+   implementation may either simply cast the array from
+   one type to the other without copying the array, or it
+   may take a full copy of the array.
+
+   Note that because the array is possibly not copied, any subsequent
+   modifications made to the mutable version of the array may be
+   shared with the immutable version.  It is safe to use, therefore, if
+   the mutable version is never modified after the freeze operation.
+
+   The non-copying implementation is supported between certain pairs
+   of array types only; one constraint is that the array types must
+   have identical representations.  In GHC, The following pairs of
+   array types have a non-copying O(1) implementation of
+   'unsafeFreeze'.  Because the optimised versions are enabled by
+   specialisations, you will need to compile with optimisation (-O) to
+   get them.
+
+     * 'Data.Array.IO.IOUArray' -> 'Data.Array.Unboxed.UArray'
+
+     * 'Data.Array.ST.STUArray' -> 'Data.Array.Unboxed.UArray'
+
+     * 'Data.Array.IO.IOArray' -> 'Data.Array.Array'
 
--- | Converts a mutable array to an immutable array /without taking a
--- copy/.  This function is \"unsafe\" because if any further
--- modifications are made to the original mutable array then they will
--- be shared with the immutable version.  It is safe to use,
--- therefore, if the mutable version is never modified after the
--- freeze operation.
+     * 'Data.Array.ST.STArray' -> 'Data.Array.Array'
+-}
+{-# INLINE unsafeFreeze #-}
 unsafeFreeze :: (Ix i, MArray a e m, IArray b e) => a i e -> m (b i e)
 unsafeFreeze = freeze
 
@@ -1615,13 +1635,34 @@ thawSTUArray (UArray l u arr) = do
 -- have a reference to the array at the point where you unsafely
 -- thaw it (and, subsequently mutate it, I suspect).
 
-{-# INLINE unsafeThaw #-}
+{- |
+   Converts an immutable array into a mutable array.  The 
+   implementation may either simply cast the array from
+   one type to the other without copying the array, or it
+   may take a full copy of the array.  
+
+   Note that because the array is possibly not copied, any subsequent
+   modifications made to the mutable version of the array may be
+   shared with the immutable version.  It is safe to use, therefore, if
+   the immutable version is never referenced again.
+
+   The non-copying implementation is supported between certain pairs
+   of array types only; one constraint is that the array types must
+   have identical representations.  In GHC, The following pairs of
+   array types have a non-copying O(1) implementation of
+   'unsafeFreeze'.  Because the optimised versions are enabled by
+   specialisations, you will need to compile with optimisation (-O) to
+   get them.
 
--- | Converts an immutable array into a mutable array /without taking
--- a copy/.  This function is \"unsafe\" because any subsequent
--- modifications made to the mutable version of the array will be
--- shared with the immutable version.  It is safe to use, therefore, if
--- the immutable version is never referenced again.
+     * 'Data.Array.Unboxed.UArray' -> 'Data.Array.IO.IOUArray'
+
+     * 'Data.Array.Unboxed.UArray' -> 'Data.Array.ST.STUArray'
+
+     * 'Data.Array.Array'  -> 'Data.Array.IO.IOArray'
+
+     * 'Data.Array.Array'  -> 'Data.Array.ST.STArray'
+-}
+{-# INLINE unsafeThaw #-}
 unsafeThaw :: (Ix i, IArray a e, MArray b e m) => a i e -> m (b i e)
 unsafeThaw = thaw