Foreign/C/String.hs

   1 {-# OPTIONS -fno-implicit-prelude #-}
   2 -----------------------------------------------------------------------------
   3 -- |
   4 -- Module      :  Foreign.C.String
   5 -- Copyright   :  (c) The FFI task force 2001
   6 -- License     :  BSD-style (see the file libraries/base/LICENSE)
   7 --
   8 -- Maintainer  :  ffi@haskell.org
   9 -- Stability   :  provisional
  10 -- Portability :  portable
  11 --
  12 -- Utilities for primitive marshaling
  13 --
  14 -----------------------------------------------------------------------------
  15
  16 module Foreign.C.String (   -- representation of strings in C
  17
  18   CString,           -- = Ptr CChar
  19   CStringLen,        -- = (CString, Int)
  20
  21   -- conversion of C strings into Haskell strings
  22   --
  23   peekCString,       -- :: CString    -> IO String
  24   peekCStringLen,    -- :: CStringLen -> IO String
  25
  26   -- conversion of Haskell strings into C strings
  27   --
  28   newCString,        -- :: String -> IO CString
  29   newCStringLen,     -- :: String -> IO CStringLen
  30
  31   -- conversion of Haskell strings into C strings using temporary storage
  32   --
  33   withCString,       -- :: String -> (CString    -> IO a) -> IO a
  34   withCStringLen,    -- :: String -> (CStringLen -> IO a) -> IO a
  35
  36   -- conversion between Haskell and C characters *ignoring* the encoding
  37   --
  38   castCharToCChar,   -- :: Char -> CChar
  39   castCCharToChar,   -- :: CChar -> Char
  40
  41   ) where
  42
  43 import Foreign.Marshal.Array
  44 import Foreign.C.Types
  45 import Foreign.Ptr
  46
  47 import Data.Word
  48
  49 #ifdef __GLASGOW_HASKELL__
  50 import GHC.List
  51 import GHC.Real
  52 import GHC.Num
  53 import GHC.IOBase
  54 import GHC.Base
  55 #endif
  56
  57 -----------------------------------------------------------------------------
  58 -- Strings
  59
  60 -- representation of strings in C
  61 -- ------------------------------
  62
  63 type CString    = Ptr CChar             -- conventional NUL terminates strings
  64 type CStringLen = (CString, Int)        -- strings with explicit length
  65
  66
  67 -- exported functions
  68 -- ------------------
  69 --
  70 -- * the following routines apply the default conversion when converting the
  71 --   C-land character encoding into the Haskell-land character encoding
  72 --
  73 --   ** NOTE: The current implementation doesn't handle conversions yet! **
  74 --
  75 -- * the routines using an explicit length tolerate NUL characters in the
  76 --   middle of a string
  77 --
  78
  79 -- marshal a NUL terminated C string into a Haskell string
  80 --
  81 peekCString    :: CString -> IO String
  82 peekCString cp  = do cs <- peekArray0 nUL cp; return (cCharsToChars cs)
  83
  84 -- marshal a C string with explicit length into a Haskell string
  85 --
  86 peekCStringLen           :: CStringLen -> IO String
  87 peekCStringLen (cp, len)  = do cs <- peekArray len cp; return (cCharsToChars cs)
  88
  89 -- marshal a Haskell string into a NUL terminated C strings
  90 --
  91 -- * the Haskell string may *not* contain any NUL characters
  92 --
  93 -- * new storage is allocated for the C string and must be explicitly freed
  94 --
  95 newCString :: String -> IO CString
  96 newCString  = newArray0 nUL . charsToCChars
  97
  98 -- marshal a Haskell string into a C string (ie, character array) with
  99 -- explicit length information
 100 --
 101 -- * new storage is allocated for the C string and must be explicitly freed
 102 --
 103 newCStringLen     :: String -> IO CStringLen
 104 newCStringLen str  = do a <- newArray (charsToCChars str)
 105                         return (pairLength str a)
 106
 107 -- marshal a Haskell string into a NUL terminated C strings using temporary
 108 -- storage
 109 --
 110 -- * the Haskell string may *not* contain any NUL characters
 111 --
 112 -- * see the lifetime constraints of `MarshalAlloc.alloca'
 113 --
 114 withCString :: String -> (CString -> IO a) -> IO a
 115 withCString  = withArray0 nUL . charsToCChars
 116
 117 -- marshal a Haskell string into a NUL terminated C strings using temporary
 118 -- storage
 119 --
 120 -- * the Haskell string may *not* contain any NUL characters
 121 --
 122 -- * see the lifetime constraints of `MarshalAlloc.alloca'
 123 --
 124 withCStringLen         :: String -> (CStringLen -> IO a) -> IO a
 125 withCStringLen str act  = withArray (charsToCChars str) $ act . pairLength str
 126
 127 -- auxilliary definitions
 128 -- ----------------------
 129
 130 -- C's end of string character
 131 --
 132 nUL :: CChar
 133 nUL  = 0
 134
 135 -- pair a C string with the length of the given Haskell string
 136 --
 137 pairLength :: String -> CString -> CStringLen
 138 pairLength  = flip (,) . length
 139
 140 -- cast [CChar] to [Char]
 141 --
 142 cCharsToChars :: [CChar] -> [Char]
 143 cCharsToChars  = map castCCharToChar
 144
 145 -- cast [Char] to [CChar]
 146 --
 147 charsToCChars :: [Char] -> [CChar]
 148 charsToCChars  = map castCharToCChar
 149
 150 castCCharToChar :: CChar -> Char
 151 castCCharToChar ch = unsafeChr (fromIntegral (fromIntegral ch :: Word8))
 152
 153 castCharToCChar :: Char -> CChar
 154 castCharToCChar ch = fromIntegral (ord ch)