1 % -----------------------------------------------------------------------------
2 % $Id: PrelCString.lhs,v 1.6 2001/11/27 14:49:10 simonmar Exp $
4 % (c) The FFI task force, 2000
7 Utilities for primitive marshaling
10 {-# OPTIONS -fno-implicit-prelude #-}
12 module PrelCString where
14 #ifdef __GLASGOW_HASKELL__
15 import PrelMarshalArray
27 -----------------------------------------------------------------------------
30 -- representation of strings in C
31 -- ------------------------------
33 type CString = Ptr CChar -- conventional NUL terminates strings
34 type CStringLen = (CString, Int) -- strings with explicit length
40 -- * the following routines apply the default conversion when converting the
41 -- C-land character encoding into the Haskell-land character encoding
43 -- ** NOTE: The current implementation doesn't handle conversions yet! **
45 -- * the routines using an explicit length tolerate NUL characters in the
49 -- marshal a NUL terminated C string into a Haskell string
51 peekCString :: CString -> IO String
52 peekCString cp = do cs <- peekArray0 nUL cp; return (cCharsToChars cs)
54 -- marshal a C string with explicit length into a Haskell string
56 peekCStringLen :: CStringLen -> IO String
57 peekCStringLen (cp, len) = do cs <- peekArray len cp; return (cCharsToChars cs)
59 -- marshal a Haskell string into a NUL terminated C strings
61 -- * the Haskell string may *not* contain any NUL characters
63 -- * new storage is allocated for the C string and must be explicitly freed
65 newCString :: String -> IO CString
66 newCString = newArray0 nUL . charsToCChars
68 -- marshal a Haskell string into a C string (ie, character array) with
69 -- explicit length information
71 -- * new storage is allocated for the C string and must be explicitly freed
73 newCStringLen :: String -> IO CStringLen
74 newCStringLen str = do a <- newArray (charsToCChars str)
75 return (pairLength str a)
77 -- marshal a Haskell string into a NUL terminated C strings using temporary
80 -- * the Haskell string may *not* contain any NUL characters
82 -- * see the lifetime constraints of `MarshalAlloc.alloca'
84 withCString :: String -> (CString -> IO a) -> IO a
85 withCString = withArray0 nUL . charsToCChars
87 -- marshal a Haskell string into a NUL terminated C strings using temporary
90 -- * the Haskell string may *not* contain any NUL characters
92 -- * see the lifetime constraints of `MarshalAlloc.alloca'
94 withCStringLen :: String -> (CStringLen -> IO a) -> IO a
95 withCStringLen str act = withArray (charsToCChars str) $ act . pairLength str
97 -- auxilliary definitions
98 -- ----------------------
100 -- C's end of string character
105 -- pair a C string with the length of the given Haskell string
107 pairLength :: String -> CString -> CStringLen
108 pairLength = flip (,) . length
110 -- cast [CChar] to [Char]
112 cCharsToChars :: [CChar] -> [Char]
113 cCharsToChars = map castCCharToChar
115 -- cast [Char] to [CChar]
117 charsToCChars :: [Char] -> [CChar]
118 charsToCChars = map castCharToCChar
120 castCCharToChar :: CChar -> Char
121 castCCharToChar ch = unsafeChr (fromIntegral (fromIntegral ch :: Word8))
123 castCharToCChar :: Char -> CChar
124 castCharToCChar ch = fromIntegral (ord ch)