-- |
-- Module : Foreign.Marshal.Utils
-- 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
-----------------------------------------------------------------------------
module Foreign.Marshal.Utils (
+ -- * General marshalling utilities
- -- combined allocation and marshalling
+ -- ** Combined allocation and marshalling
--
- withObject, -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
- {- FIXME: should be `with' -}
+ with, -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
new, -- :: Storable a => a -> IO (Ptr a)
- -- marshalling of Boolean values (non-zero corresponds to `True')
+ -- ** Marshalling of Boolean values (non-zero corresponds to 'True')
--
fromBool, -- :: Num a => Bool -> a
toBool, -- :: Num a => a -> Bool
- -- marshalling of Maybe values
+ -- ** Marshalling of Maybe values
--
maybeNew, -- :: ( a -> IO (Ptr a))
-- -> (Maybe a -> IO (Ptr a))
maybePeek, -- :: (Ptr a -> IO b )
-- -> (Ptr a -> IO (Maybe b))
- -- marshalling lists of storable objects
+ -- ** Marshalling lists of storable objects
--
withMany, -- :: (a -> (b -> res) -> res) -> [a] -> ([b] -> res) -> res
- -- Haskellish interface to memcpy and memmove
- -- (argument order: destination, source)
+ -- ** Haskellish interface to memcpy and memmove
+ -- | (argument order: destination, source)
--
copyBytes, -- :: Ptr a -> Ptr a -> Int -> IO ()
- moveBytes -- :: Ptr a -> Ptr a -> Int -> IO ()
+ moveBytes, -- :: Ptr a -> Ptr a -> Int -> IO ()
+
+ -- ** DEPRECATED FUNCTIONS (don\'t use; they may disappear at any time)
+ --
+ withObject -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
) where
import Data.Maybe
-
-#ifdef __GLASGOW_HASKELL__
import Foreign.Ptr ( Ptr, nullPtr )
-import GHC.Storable ( Storable(poke) )
-import Foreign.C.TypesISO ( CSize )
+import Foreign.Storable ( Storable(poke) )
+import Foreign.C.Types ( CSize, CInt(..) )
import Foreign.Marshal.Alloc ( malloc, alloca )
+
+#ifdef __GLASGOW_HASKELL__
import GHC.IOBase
import GHC.Real ( fromIntegral )
import GHC.Num
-- combined allocation and marshalling
-- -----------------------------------
--- allocate storage for a value and marshal it into this storage
+-- |Allocate storage for a value and marshal it into this storage
--
new :: Storable a => a -> IO (Ptr a)
new val =
poke ptr val
return ptr
--- allocate temporary storage for a value and marshal it into this storage
+-- |Allocate temporary storage for a value and marshal it into this storage
--
--- * see the life time constraints imposed by `alloca'
+-- * see the life time constraints imposed by 'alloca'
--
-{- FIXME: should be called `with' -}
-withObject :: Storable a => a -> (Ptr a -> IO b) -> IO b
-withObject val f =
+with :: Storable a => a -> (Ptr a -> IO b) -> IO b
+with val f =
alloca $ \ptr -> do
poke ptr val
res <- f ptr
return res
+-- old DEPRECATED name (don't use; may disappear at any time)
+--
+withObject :: Storable a => a -> (Ptr a -> IO b) -> IO b
+{-# DEPRECATED withObject "use `with' instead" #-}
+withObject = with
+
--- marshalling of Boolean values (non-zero corresponds to `True')
+-- marshalling of Boolean values (non-zero corresponds to 'True')
-- -----------------------------
--- convert a Haskell Boolean to its numeric representation
+-- |Convert a Haskell 'Bool' to its numeric representation
--
fromBool :: Num a => Bool -> a
fromBool False = 0
fromBool True = 1
--- convert a Boolean in numeric representation to a Haskell value
+-- |Convert a Boolean in numeric representation to a Haskell value
--
toBool :: Num a => a -> Bool
toBool = (/= 0)
-- marshalling of Maybe values
-- ---------------------------
--- allocate storage and marshall a storable value wrapped into a `Maybe'
+-- |Allocate storage and marshall a storable value wrapped into a 'Maybe'
--
--- * the `nullPtr' is used to represent `Nothing'
+-- * the 'nullPtr' is used to represent 'Nothing'
--
maybeNew :: ( a -> IO (Ptr a))
-> (Maybe a -> IO (Ptr a))
maybeNew = maybe (return nullPtr)
--- converts a withXXX combinator into one marshalling a value wrapped into a
--- `Maybe'
+-- |Converts a @withXXX@ combinator into one marshalling a value wrapped into a
+-- 'Maybe'
--
maybeWith :: ( a -> (Ptr b -> IO c) -> IO c)
-> (Maybe a -> (Ptr b -> IO c) -> IO c)
maybeWith = maybe ($ nullPtr)
--- convert a peek combinator into a one returning `Nothing' if applied to a
--- `nullPtr'
+-- |Convert a peek combinator into a one returning 'Nothing' if applied to a
+-- 'nullPtr'
--
maybePeek :: (Ptr a -> IO b) -> Ptr a -> IO (Maybe b)
maybePeek peek ptr | ptr == nullPtr = return Nothing
-- marshalling lists of storable objects
-- -------------------------------------
--- replicates a withXXX combinator over a list of objects, yielding a list of
+-- |Replicates a @withXXX@ combinator over a list of objects, yielding a list of
-- marshalled objects
--
withMany :: (a -> (b -> res) -> res) -- withXXX combinator for one object
-- Haskellish interface to memcpy and memmove
-- ------------------------------------------
--- copies the given number of bytes from the second area (source) into the
--- first (destination); the copied areas may *not* overlap
+-- |Copies the given number of bytes from the second area (source) into the
+-- first (destination); the copied areas may /not/ overlap
--
copyBytes :: Ptr a -> Ptr a -> Int -> IO ()
copyBytes dest src size = memcpy dest src (fromIntegral size)
--- copies the given number of elements from the second area (source) into the
--- first (destination); the copied areas *may* overlap
+-- |Copies the given number of elements from the second area (source) into the
+-- first (destination); the copied areas /may/ overlap
--
moveBytes :: Ptr a -> Ptr a -> Int -> IO ()
moveBytes dest src size = memmove dest src (fromIntegral size)
-- auxilliary routines
-- -------------------
--- basic C routines needed for memory copying
+-- |Basic C routines needed for memory copying
--
-foreign import ccall unsafe memcpy :: Ptr a -> Ptr a -> CSize -> IO ()
-foreign import ccall unsafe memmove :: Ptr a -> Ptr a -> CSize -> IO ()
+foreign import ccall unsafe "string.h" memcpy :: Ptr a -> Ptr a -> CSize -> IO ()
+foreign import ccall unsafe "string.h" memmove :: Ptr a -> Ptr a -> CSize -> IO ()
projects / ghc-base.git / blobdiff