Chapter 27
Foreign.C.String
     
                                                                                   
                                                                                   
     
module Foreign.C.String (
 
    CString,  CStringLen,  peekCString,  peekCStringLen,  newCString,
 
    newCStringLen,  withCString,  withCStringLen,  charIsRepresentable,
 
    castCharToCChar,  castCCharToChar,  castCharToCUChar,  castCUCharToChar,
 
    castCharToCSChar,  castCSCharToChar,  peekCAString,  peekCAStringLen,
 
    newCAString,  newCAStringLen,  withCAString,  withCAStringLen,  CWString,
 
    CWStringLen,  peekCWString,  peekCWStringLen,  newCWString,
 
    newCWStringLen,  withCWString,  withCWStringLen
 
  ) where
      
 Utilities for primitive marshalling of C strings.
 
 The marshalling converts each Haskell character, representing a Unicode code point, to one or more bytes in a
manner that, by default, is determined by the current locale. As a consequence, no guarantees can be made about the
relative length of a Haskell string and its corresponding C string, and therefore all the marshalling routines include
memory allocation. The translation between Unicode and the encoding of the current locale may be
lossy.
27.1     C strings 
     
 - 
 
- 
     A C string is a reference to an array of C characters terminated by NUL.
     
     
 - 
 | type CStringLen = (Ptr CChar, Int) |  
 
 
- 
     A  string  with  explicit  length  information  in  bytes  instead  of  a  terminating  NUL  (allowing  NUL
     characters in the middle of the string).
     
27.1.1     Using a locale-dependent encoding 
 Currently these functions are identical to their CAString counterparts; eventually they will use an encoding
determined by the current locale.
 
                                                                                   
                                                                                   
     
 - 
 | peekCString :: CString -> IO String |  
 
 
- 
     Marshal a NUL terminated C string into a Haskell string.
     
     
 - 
 | peekCStringLen :: CStringLen -> IO String |  
 
 
- 
     Marshal a C string with explicit length into a Haskell string.
     
     
 - 
 | newCString :: String -> IO CString |  
 
 
- 
     Marshal a Haskell string into a NUL terminated C string.
         
         - the Haskell string may not contain any NUL characters
         
- new    storage    is    allocated    for    the    C    string    and    must    be    explicitly    freed    using
         Foreign.Marshal.Alloc.free or Foreign.Marshal.Alloc.finalizerFree.
         
 
     
 - 
 | newCStringLen :: String -> IO CStringLen |  
 
 
- 
     Marshal a Haskell string into a C string (ie, character array) with explicit length information.
         
         - new    storage    is    allocated    for    the    C    string    and    must    be    explicitly    freed    using
         Foreign.Marshal.Alloc.free or Foreign.Marshal.Alloc.finalizerFree.
         
 
     
 - 
 | withCString :: String -> (CString -> IO a) -> IO a |  
 
 
- 
     Marshal a Haskell string into a NUL terminated C string using temporary storage.
                                                                                   
                                                                                   
         
         - the Haskell string may not contain any NUL characters
         
- the memory is freed when the subcomputation terminates (either normally or via an exception),
         so the pointer to the temporary storage must not be used after this.
         
 
     
 - 
 | withCStringLen :: String -> (CStringLen -> IO a) -> IO a |  
 
 
- 
     Marshal a Haskell string into a C string (ie, character array) in temporary storage, with explicit length
     information.
         
         - the memory is freed when the subcomputation terminates (either normally or via an exception),
         so the pointer to the temporary storage must not be used after this.
         
 
     
 - 
 | charIsRepresentable :: Char -> IO Bool |  
 
 
- 
     Determines whether a character can be accurately encoded in a CString. Unrepresentable characters
     are converted to '?'.
      Currently only Latin-1 characters are representable.
      
27.1.2     Using 8-bit characters 
 These variants of the above functions are for use with C libraries that are ignorant of Unicode. These functions
should be used with care, as a loss of information can occur.
 
     
 - 
 | castCharToCChar :: Char -> CChar |  
 
 
- 
     Convert a Haskell character to a C character. This function is only safe on the first 256 characters.
     
                                                                                   
                                                                                   
     
 - 
 | castCCharToChar :: CChar -> Char |  
 
 
- 
     Convert a C byte, representing a Latin-1 character, to the corresponding Haskell character.
     
     
 - 
 | castCharToCUChar :: Char -> CUChar |  
 
 
- 
     Convert  a  Haskell  character  to  a  C  unsigned char.  This  function  is  only  safe  on  the  first  256
     characters.
     
     
 - 
 | castCUCharToChar :: CUChar -> Char |  
 
 
- 
     Convert  a  C  unsigned char,  representing  a  Latin-1  character,  to  the  corresponding  Haskell
     character.
     
     
 - 
 | castCharToCSChar :: Char -> CSChar |  
 
 
- 
     Convert  a  Haskell  character  to  a  C  signed char.  This  function  is  only  safe  on  the  first  256
     characters.
     
     
 - 
 | castCSCharToChar :: CSChar -> Char |  
 
 
- 
     Convert a C signed char, representing a Latin-1 character, to the corresponding Haskell character.
     
     
 - 
 | peekCAString :: CString -> IO String |  
 
 
- 
     Marshal a NUL terminated C string into a Haskell string.
     
                                                                                   
                                                                                   
     
 - 
 | peekCAStringLen :: CStringLen -> IO String |  
 
 
- 
     Marshal a C string with explicit length into a Haskell string.
     
     
 - 
 | newCAString :: String -> IO CString |  
 
 
- 
     Marshal a Haskell string into a NUL terminated C string.
         
         - the Haskell string may not contain any NUL characters
         
- new    storage    is    allocated    for    the    C    string    and    must    be    explicitly    freed    using
         Foreign.Marshal.Alloc.free or Foreign.Marshal.Alloc.finalizerFree.
         
 
     
 - 
 | newCAStringLen :: String -> IO CStringLen |  
 
 
- 
     Marshal a Haskell string into a C string (ie, character array) with explicit length information.
         
         - new    storage    is    allocated    for    the    C    string    and    must    be    explicitly    freed    using
         Foreign.Marshal.Alloc.free or Foreign.Marshal.Alloc.finalizerFree.
         
 
     
 - 
 | withCAString :: String -> (CString -> IO a) -> IO a |  
 
 
- 
     Marshal a Haskell string into a NUL terminated C string using temporary storage.
         
         - the Haskell string may not contain any NUL characters
         
- the memory is freed when the subcomputation terminates (either normally or via an exception),
         so the pointer to the temporary storage must not be used after this.
         
 
     
 - 
 | withCAStringLen :: String -> (CStringLen -> IO a) -> IO a |  
 
 
- 
     Marshal a Haskell string into a C string (ie, character array) in temporary storage, with explicit length
     information.
         
         - the memory is freed when the subcomputation terminates (either normally or via an exception),
         so the pointer to the temporary storage must not be used after this.
         
 
27.2     C wide strings 
 These variants of the above functions are for use with C libraries that encode Unicode using the C wchar_t type in
a system-dependent way. The only encodings supported are
     
     - UTF-32 (the C compiler defines __STDC_ISO_10646__), or
     
- UTF-16 (as used on Windows systems).
     
     
 - 
 | type CWString = Ptr CWchar |  
 
 
- 
     A C wide string is a reference to an array of C wide characters terminated by NUL.
     
     
 - 
 | type CWStringLen = (Ptr CWchar, Int) |  
 
 
- 
     A wide character string with explicit length information in CWchars instead of a terminating NUL
     (allowing NUL characters in the middle of the string).
     
     
 - 
 | peekCWString :: CWString -> IO String |  
 
 
- 
     Marshal a NUL terminated C wide string into a Haskell string.
     
     
 - 
 | peekCWStringLen :: CWStringLen -> IO String |  
 
 
- 
     Marshal a C wide string with explicit length into a Haskell string.
     
     
 - 
 | newCWString :: String -> IO CWString |  
 
 
- 
     Marshal a Haskell string into a NUL terminated C wide string.
         
         - the Haskell string may not contain any NUL characters
         
- new   storage   is   allocated   for   the   C   wide   string   and   must   be   explicitly   freed   using
         Foreign.Marshal.Alloc.free or Foreign.Marshal.Alloc.finalizerFree.
         
 
     
 - 
 | newCWStringLen :: String -> IO CWStringLen |  
 
 
- 
     Marshal a Haskell string into a C wide string (ie, wide character array) with explicit length information.
         
         - new   storage   is   allocated   for   the   C   wide   string   and   must   be   explicitly   freed   using
         Foreign.Marshal.Alloc.free or Foreign.Marshal.Alloc.finalizerFree.
         
 
                                                                                   
                                                                                   
     
 - 
 | withCWString :: String -> (CWString -> IO a) -> IO a |  
 
 
- 
     Marshal a Haskell string into a NUL terminated C wide string using temporary storage.
         
         - the Haskell string may not contain any NUL characters
         
- the memory is freed when the subcomputation terminates (either normally or via an exception),
         so the pointer to the temporary storage must not be used after this.
         
 
     
 - 
 | withCWStringLen :: String -> (CWStringLen -> IO a) -> IO a |  
 
 
- 
     Marshal a Haskell string into a NUL terminated C wide string using temporary storage.
         
         - the Haskell string may not contain any NUL characters
         
- the memory is freed when the subcomputation terminates (either normally or via an exception),
         so the pointer to the temporary storage must not be used after this.