| ||||||||
| ||||||||
| ||||||||
| 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 | ||||||||
| 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.
| ||||||||
| newCStringLen :: String -> IO CStringLen | ||||||||
Marshal a Haskell string into a C string (ie, character array) with explicit length information.
| ||||||||
| withCString :: String -> (CString -> IO a) -> IO a | ||||||||
Marshal a Haskell string into a NUL terminated C string using temporary storage.
| ||||||||
| 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.
| ||||||||
| 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.
| ||||||||
| newCAStringLen :: String -> IO CStringLen | ||||||||
Marshal a Haskell string into a C string (ie, character array) with explicit length information.
| ||||||||
| withCAString :: String -> (CString -> IO a) -> IO a | ||||||||
Marshal a Haskell string into a NUL terminated C string using temporary storage.
| ||||||||
| 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.
| ||||||||
| 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
| ||||||||
| 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.
| ||||||||
| newCWStringLen :: String -> IO CWStringLen | ||||||||
Marshal a Haskell string into a C wide string (ie, wide character array) with explicit length information.
| ||||||||
| withCWString :: String -> (CWString -> IO a) -> IO a | ||||||||
Marshal a Haskell string into a NUL terminated C wide string using temporary storage.
| ||||||||
| withCWStringLen :: String -> (CWStringLen -> IO a) -> IO a | ||||||||
Marshal a Haskell string into a NUL terminated C wide string using temporary storage.
| ||||||||
| Produced by Haddock version 0.8 |