Haskell Hierarchical Libraries (base package)ContentsIndex
Foreign.C.String
Portability portable
Stability provisional
Maintainer ffi@haskell.org
Contents
C strings
Using a locale-dependent encoding
Using 8-bit characters
C wide strings
Description

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.

Synopsis
type CString = Ptr CChar
type CStringLen = (Ptr CChar, Int)
peekCString :: CString -> IO String
peekCStringLen :: CStringLen -> IO String
newCString :: String -> IO CString
newCStringLen :: String -> IO CStringLen
withCString :: String -> (CString -> IO a) -> IO a
withCStringLen :: String -> (CStringLen -> IO a) -> IO a
charIsRepresentable :: Char -> IO Bool
castCharToCChar :: Char -> CChar
castCCharToChar :: CChar -> Char
peekCAString :: CString -> IO String
peekCAStringLen :: CStringLen -> IO String
newCAString :: String -> IO CString
newCAStringLen :: String -> IO CStringLen
withCAString :: String -> (CString -> IO a) -> IO a
withCAStringLen :: String -> (CStringLen -> IO a) -> IO a
type CWString = Ptr CWchar
type CWStringLen = (Ptr CWchar, Int)
peekCWString :: CWString -> IO String
peekCWStringLen :: CWStringLen -> IO String
newCWString :: String -> IO CWString
newCWStringLen :: String -> IO CWStringLen
withCWString :: String -> (CWString -> IO a) -> IO a
withCWStringLen :: String -> (CWStringLen -> IO a) -> IO a
C strings
type CString = Ptr CChar
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).
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
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
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
  • see the lifetime constraints of alloca
withCStringLen :: String -> (CStringLen -> 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
  • see the lifetime constraints of alloca
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.

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.
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
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
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
  • see the lifetime constraints of alloca
withCAStringLen :: String -> (CStringLen -> 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
  • see the lifetime constraints of alloca
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 bytes 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 string and must be explicitly freed
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 string and must be explicitly freed
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
  • see the lifetime constraints of alloca
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
  • see the lifetime constraints of alloca
Produced by Haddock version 0.6