X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Foreign%2FMarshal%2FArray.hs;h=16a3e47bb3567d322067da7c3bb07f3a69934e95;hb=f7a485978f04e84b086f1974b88887cc72d832d0;hp=55b9c11403d1e3f21ee33d068a0d59c9071d1d45;hpb=746ef6a7fd71bb1e9ebe3cd107c5f9f79f3b7a68;p=ghc-base.git diff --git a/Foreign/Marshal/Array.hs b/Foreign/Marshal/Array.hs index 55b9c11..16a3e47 100644 --- a/Foreign/Marshal/Array.hs +++ b/Foreign/Marshal/Array.hs @@ -3,7 +3,7 @@ -- | -- Module : Foreign.Marshal.Array -- Copyright : (c) The FFI task force 2001 --- License : BSD-style (see the file libraries/core/LICENSE) +-- License : BSD-style (see the file libraries/base/LICENSE) -- -- Maintainer : ffi@haskell.org -- Stability : provisional @@ -15,8 +15,9 @@ ----------------------------------------------------------------------------- module Foreign.Marshal.Array ( + -- * Marshalling arrays - -- allocation + -- ** Allocation -- mallocArray, -- :: Storable a => Int -> IO (Ptr a) mallocArray0, -- :: Storable a => Int -> IO (Ptr a) @@ -27,7 +28,7 @@ module Foreign.Marshal.Array ( reallocArray, -- :: Storable a => Ptr a -> Int -> IO (Ptr a) reallocArray0, -- :: Storable a => Ptr a -> Int -> IO (Ptr a) - -- marshalling + -- ** Marshalling -- peekArray, -- :: Storable a => Int -> Ptr a -> IO [a] peekArray0, -- :: (Storable a, Eq a) => a -> Ptr a -> IO [a] @@ -35,7 +36,7 @@ module Foreign.Marshal.Array ( pokeArray, -- :: Storable a => Ptr a -> [a] -> IO () pokeArray0, -- :: Storable a => a -> Ptr a -> [a] -> IO () - -- combined allocation and marshalling + -- ** Combined allocation and marshalling -- newArray, -- :: Storable a => [a] -> IO (Ptr a) newArray0, -- :: Storable a => a -> [a] -> IO (Ptr a) @@ -43,16 +44,17 @@ module Foreign.Marshal.Array ( withArray, -- :: Storable a => [a] -> (Ptr a -> IO b) -> IO b withArray0, -- :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b - -- copying (argument order: destination, source) - -- + -- ** Copying + + -- | (argument order: destination, source) copyArray, -- :: Storable a => Ptr a -> Ptr a -> Int -> IO () moveArray, -- :: Storable a => Ptr a -> Ptr a -> Int -> IO () - -- finding the length + -- ** Finding the length -- lengthArray0, -- :: (Storable a, Eq a) => a -> Ptr a -> IO Int - -- indexing + -- ** Indexing -- advancePtr, -- :: Storable a => Ptr a -> Int -> Ptr a ) where @@ -62,7 +64,7 @@ import Control.Monad #ifdef __GLASGOW_HASKELL__ import Foreign.Ptr (Ptr, plusPtr) import GHC.Storable (Storable(sizeOf,peekElemOff,pokeElemOff)) -import Foreign.Marshal.Alloc (mallocBytes, allocaBytes, reallocBytes) +import Foreign.Marshal.Alloc (alloca, mallocBytes, allocaBytes, reallocBytes) import Foreign.Marshal.Utils (copyBytes, moveBytes) import GHC.IOBase import GHC.Num @@ -74,7 +76,7 @@ import GHC.Base -- allocation -- ---------- --- allocate storage for the given number of elements of a storable type +-- |Allocate storage for the given number of elements of a storable type. -- mallocArray :: Storable a => Int -> IO (Ptr a) mallocArray = doMalloc undefined @@ -82,14 +84,14 @@ mallocArray = doMalloc undefined doMalloc :: Storable a => a -> Int -> IO (Ptr a) doMalloc dummy size = mallocBytes (size * sizeOf dummy) --- like `mallocArray', but add an extra element to signal the end of the array +-- |Like 'mallocArray', but add an extra element to signal the end of the array -- mallocArray0 :: Storable a => Int -> IO (Ptr a) mallocArray0 size = mallocArray (size + 1) --- temporarily allocate space for the given number of elements +-- |Temporarily allocate space for the given number of elements. -- --- * see `MarshalAlloc.alloca' for the storage lifetime constraints +-- * see 'Foreign.Marshal.Alloc.alloca' for the storage lifetime constraints -- allocaArray :: Storable a => Int -> (Ptr a -> IO b) -> IO b allocaArray = doAlloca undefined @@ -97,12 +99,12 @@ allocaArray = doAlloca undefined doAlloca :: Storable a => a -> Int -> (Ptr a -> IO b) -> IO b doAlloca dummy size = allocaBytes (size * sizeOf dummy) --- like `allocaArray', but add an extra element to signal the end of the array +-- |Like 'allocaArray', but add an extra element to signal the end of the array -- allocaArray0 :: Storable a => Int -> (Ptr a -> IO b) -> IO b allocaArray0 size = allocaArray (size + 1) --- adjust the size of an array +-- |Adjust the size of an array -- reallocArray :: Storable a => Ptr a -> Int -> IO (Ptr a) reallocArray = doRealloc undefined @@ -110,7 +112,7 @@ reallocArray = doRealloc undefined doRealloc :: Storable a => a -> Ptr a -> Int -> IO (Ptr a) doRealloc dummy ptr size = reallocBytes ptr (size * sizeOf dummy) --- adjust the size of an array while adding an element for the end marker +-- |Adjust the size of an array while adding an element for the end marker -- reallocArray0 :: Storable a => Ptr a -> Int -> IO (Ptr a) reallocArray0 ptr size = reallocArray ptr (size + 1) @@ -119,7 +121,7 @@ reallocArray0 ptr size = reallocArray ptr (size + 1) -- marshalling -- ----------- --- convert an array of given length into a Haskell list. This version +-- |Convert an array of given length into a Haskell list. This version -- traverses the array backwards using an accumulating parameter, -- which uses constant stack space. The previous version using mapM -- needed linear stack space. @@ -131,7 +133,7 @@ peekArray size ptr | size <= 0 = return [] f 0 acc = do e <- peekElemOff ptr 0; return (e:acc) f n acc = do e <- peekElemOff ptr n; f (n-1) (e:acc) --- convert an array terminated by the given end marker into a Haskell list +-- |Convert an array terminated by the given end marker into a Haskell list -- peekArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO [a] peekArray0 marker ptr = loop 0 @@ -142,12 +144,12 @@ peekArray0 marker ptr = loop 0 rest <- loop (i+1) return (val:rest) --- write the list elements consecutive into memory +-- |Write the list elements consecutive into memory -- pokeArray :: Storable a => Ptr a -> [a] -> IO () pokeArray ptr vals = zipWithM_ (pokeElemOff ptr) [0..] vals --- write the list elements consecutive into memory and terminate them with the +-- |Write the list elements consecutive into memory and terminate them with the -- given marker element -- pokeArray0 :: Storable a => a -> Ptr a -> [a] -> IO () @@ -159,7 +161,7 @@ pokeArray0 marker ptr vals = do -- combined allocation and marshalling -- ----------------------------------- --- write a list of storable elements into a newly allocated, consecutive +-- |Write a list of storable elements into a newly allocated, consecutive -- sequence of storable values -- newArray :: Storable a => [a] -> IO (Ptr a) @@ -168,7 +170,7 @@ newArray vals = do pokeArray ptr vals return ptr --- write a list of storable elements into a newly allocated, consecutive +-- |Write a list of storable elements into a newly allocated, consecutive -- sequence of storable values, where the end is fixed by the given end marker -- newArray0 :: Storable a => a -> [a] -> IO (Ptr a) @@ -177,7 +179,7 @@ newArray0 marker vals = do pokeArray0 marker ptr vals return ptr --- temporarily store a list of storable values in memory +-- |Temporarily store a list of storable values in memory -- withArray :: Storable a => [a] -> (Ptr a -> IO b) -> IO b withArray vals f = @@ -188,7 +190,7 @@ withArray vals f = where len = length vals --- like `withArray', but a terminator indicates where the array ends +-- |Like 'withArray', but a terminator indicates where the array ends -- withArray0 :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b withArray0 marker vals f = @@ -203,8 +205,8 @@ withArray0 marker vals f = -- copying (argument order: destination, source) -- ------- --- copy the given number of elements from the second array (source) into the --- first array (destination); the copied areas may *not* overlap +-- |Copy the given number of elements from the second array (source) into the +-- first array (destination); the copied areas may /not/ overlap -- copyArray :: Storable a => Ptr a -> Ptr a -> Int -> IO () copyArray = doCopy undefined @@ -212,8 +214,8 @@ copyArray = doCopy undefined doCopy :: Storable a => a -> Ptr a -> Ptr a -> Int -> IO () doCopy dummy dest src size = copyBytes dest src (size * sizeOf dummy) --- copy the given number of elements from the second array (source) into the --- first array (destination); the copied areas *may* overlap +-- |Copy the given number of elements from the second array (source) into the +-- first array (destination); the copied areas /may/ overlap -- moveArray :: Storable a => Ptr a -> Ptr a -> Int -> IO () moveArray = doMove undefined @@ -225,7 +227,7 @@ moveArray = doMove undefined -- finding the length -- ------------------ --- return the number of elements in an array, excluding the terminator +-- |Return the number of elements in an array, excluding the terminator -- lengthArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO Int lengthArray0 marker ptr = loop 0 @@ -238,7 +240,7 @@ lengthArray0 marker ptr = loop 0 -- indexing -- -------- --- advance a pointer into an array by the given number of elements +-- |Advance a pointer into an array by the given number of elements -- advancePtr :: Storable a => Ptr a -> Int -> Ptr a advancePtr = doAdvance undefined