[project @ 2002-04-24 16:31:37 by simonmar]
[packages/base.git] / Foreign / Marshal / Utils.hs
1 {-# OPTIONS -fno-implicit-prelude #-}
2 -----------------------------------------------------------------------------
3 -- |
4 -- Module : Foreign.Marshal.Utils
5 -- Copyright : (c) The FFI task force 2001
6 -- License : BSD-style (see the file libraries/core/LICENSE)
7 --
8 -- Maintainer : ffi@haskell.org
9 -- Stability : provisional
10 -- Portability : portable
11 --
12 -- $Id: Utils.hs,v 1.4 2002/04/24 16:31:44 simonmar Exp $
13 --
14 -- Utilities for primitive marshaling
15 --
16 -----------------------------------------------------------------------------
17
18 module Foreign.Marshal.Utils (
19
20 -- combined allocation and marshalling
21 --
22 withObject, -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
23 {- FIXME: should be `with' -}
24 new, -- :: Storable a => a -> IO (Ptr a)
25
26 -- marshalling of Boolean values (non-zero corresponds to `True')
27 --
28 fromBool, -- :: Num a => Bool -> a
29 toBool, -- :: Num a => a -> Bool
30
31 -- marshalling of Maybe values
32 --
33 maybeNew, -- :: ( a -> IO (Ptr a))
34 -- -> (Maybe a -> IO (Ptr a))
35 maybeWith, -- :: ( a -> (Ptr b -> IO c) -> IO c)
36 -- -> (Maybe a -> (Ptr b -> IO c) -> IO c)
37 maybePeek, -- :: (Ptr a -> IO b )
38 -- -> (Ptr a -> IO (Maybe b))
39
40 -- marshalling lists of storable objects
41 --
42 withMany, -- :: (a -> (b -> res) -> res) -> [a] -> ([b] -> res) -> res
43
44 -- Haskellish interface to memcpy and memmove
45 -- (argument order: destination, source)
46 --
47 copyBytes, -- :: Ptr a -> Ptr a -> Int -> IO ()
48 moveBytes -- :: Ptr a -> Ptr a -> Int -> IO ()
49 ) where
50
51 import Data.Maybe
52
53 #ifdef __GLASGOW_HASKELL__
54 import Foreign.Ptr ( Ptr, nullPtr )
55 import GHC.Storable ( Storable(poke) )
56 import Foreign.C.TypesISO ( CSize )
57 import Foreign.Marshal.Alloc ( malloc, alloca )
58 import GHC.IOBase
59 import GHC.Real ( fromIntegral )
60 import GHC.Num
61 import GHC.Base
62 #endif
63
64 -- combined allocation and marshalling
65 -- -----------------------------------
66
67 -- allocate storage for a value and marshal it into this storage
68 --
69 new :: Storable a => a -> IO (Ptr a)
70 new val =
71 do
72 ptr <- malloc
73 poke ptr val
74 return ptr
75
76 -- allocate temporary storage for a value and marshal it into this storage
77 --
78 -- * see the life time constraints imposed by `alloca'
79 --
80 {- FIXME: should be called `with' -}
81 withObject :: Storable a => a -> (Ptr a -> IO b) -> IO b
82 withObject val f =
83 alloca $ \ptr -> do
84 poke ptr val
85 res <- f ptr
86 return res
87
88
89 -- marshalling of Boolean values (non-zero corresponds to `True')
90 -- -----------------------------
91
92 -- convert a Haskell Boolean to its numeric representation
93 --
94 fromBool :: Num a => Bool -> a
95 fromBool False = 0
96 fromBool True = 1
97
98 -- convert a Boolean in numeric representation to a Haskell value
99 --
100 toBool :: Num a => a -> Bool
101 toBool = (/= 0)
102
103
104 -- marshalling of Maybe values
105 -- ---------------------------
106
107 -- allocate storage and marshall a storable value wrapped into a `Maybe'
108 --
109 -- * the `nullPtr' is used to represent `Nothing'
110 --
111 maybeNew :: ( a -> IO (Ptr a))
112 -> (Maybe a -> IO (Ptr a))
113 maybeNew = maybe (return nullPtr)
114
115 -- converts a withXXX combinator into one marshalling a value wrapped into a
116 -- `Maybe'
117 --
118 maybeWith :: ( a -> (Ptr b -> IO c) -> IO c)
119 -> (Maybe a -> (Ptr b -> IO c) -> IO c)
120 maybeWith = maybe ($ nullPtr)
121
122 -- convert a peek combinator into a one returning `Nothing' if applied to a
123 -- `nullPtr'
124 --
125 maybePeek :: (Ptr a -> IO b) -> Ptr a -> IO (Maybe b)
126 maybePeek peek ptr | ptr == nullPtr = return Nothing
127 | otherwise = do a <- peek ptr; return (Just a)
128
129
130 -- marshalling lists of storable objects
131 -- -------------------------------------
132
133 -- replicates a withXXX combinator over a list of objects, yielding a list of
134 -- marshalled objects
135 --
136 withMany :: (a -> (b -> res) -> res) -- withXXX combinator for one object
137 -> [a] -- storable objects
138 -> ([b] -> res) -- action on list of marshalled obj.s
139 -> res
140 withMany _ [] f = f []
141 withMany withFoo (x:xs) f = withFoo x $ \x' ->
142 withMany withFoo xs (\xs' -> f (x':xs'))
143
144
145 -- Haskellish interface to memcpy and memmove
146 -- ------------------------------------------
147
148 -- copies the given number of bytes from the second area (source) into the
149 -- first (destination); the copied areas may *not* overlap
150 --
151 copyBytes :: Ptr a -> Ptr a -> Int -> IO ()
152 copyBytes dest src size = memcpy dest src (fromIntegral size)
153
154 -- copies the given number of elements from the second area (source) into the
155 -- first (destination); the copied areas *may* overlap
156 --
157 moveBytes :: Ptr a -> Ptr a -> Int -> IO ()
158 moveBytes dest src size = memmove dest src (fromIntegral size)
159
160
161 -- auxilliary routines
162 -- -------------------
163
164 -- basic C routines needed for memory copying
165 --
166 foreign import ccall unsafe memcpy :: Ptr a -> Ptr a -> CSize -> IO ()
167 foreign import ccall unsafe memmove :: Ptr a -> Ptr a -> CSize -> IO ()