Copyright | (c) The FFI task force 2001 |
---|---|
License | BSD-style (see the file libraries/base/LICENSE) |
Maintainer | [email protected] |
Stability | provisional |
Portability | portable |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
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.
type CString = Ptr CChar Source
A C string is a reference to an array of C characters terminated by NUL.
type CStringLen = (Ptr CChar, Int) Source
A string with explicit length information in bytes instead of a terminating NUL (allowing NUL characters in the middle of the string).
These functions are different from their CAString
counterparts in that they will use an encoding determined by the current locale, rather than always assuming ASCII.
peekCString :: CString -> IO String Source
Marshal a NUL terminated C string into a Haskell string.
peekCStringLen :: CStringLen -> IO String Source
Marshal a C string with explicit length into a Haskell string.
newCString :: String -> IO CString Source
Marshal a Haskell string into a NUL terminated C string.
free
or finalizerFree
.newCStringLen :: String -> IO CStringLen Source
Marshal a Haskell string into a C string (ie, character array) with explicit length information.
free
or finalizerFree
.withCString :: String -> (CString -> IO a) -> IO a Source
Marshal a Haskell string into a NUL terminated C string using temporary storage.
withCStringLen :: String -> (CStringLen -> IO a) -> IO a Source
Marshal a Haskell string into a C string (ie, character array) in temporary storage, with explicit length information.
charIsRepresentable :: Char -> IO Bool Source
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 Source
Convert a Haskell character to a C character. This function is only safe on the first 256 characters.
castCCharToChar :: CChar -> Char Source
Convert a C byte, representing a Latin-1 character, to the corresponding Haskell character.
castCharToCUChar :: Char -> CUChar Source
Convert a Haskell character to a C unsigned char
. This function is only safe on the first 256 characters.
castCUCharToChar :: CUChar -> Char Source
Convert a C unsigned char
, representing a Latin-1 character, to the corresponding Haskell character.
castCharToCSChar :: Char -> CSChar Source
Convert a Haskell character to a C signed char
. This function is only safe on the first 256 characters.
castCSCharToChar :: CSChar -> Char Source
Convert a C signed char
, representing a Latin-1 character, to the corresponding Haskell character.
peekCAString :: CString -> IO String Source
Marshal a NUL terminated C string into a Haskell string.
peekCAStringLen :: CStringLen -> IO String Source
Marshal a C string with explicit length into a Haskell string.
newCAString :: String -> IO CString Source
Marshal a Haskell string into a NUL terminated C string.
free
or finalizerFree
.newCAStringLen :: String -> IO CStringLen Source
Marshal a Haskell string into a C string (ie, character array) with explicit length information.
free
or finalizerFree
.withCAString :: String -> (CString -> IO a) -> IO a Source
Marshal a Haskell string into a NUL terminated C string using temporary storage.
withCAStringLen :: String -> (CStringLen -> IO a) -> IO a Source
Marshal a Haskell string into a C string (ie, character array) in temporary storage, with explicit length information.
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
201103L
), ortype CWString = Ptr CWchar Source
A C wide string is a reference to an array of C wide characters terminated by NUL.
type CWStringLen = (Ptr CWchar, Int) Source
A wide character string with explicit length information in CWchar
s instead of a terminating NUL (allowing NUL characters in the middle of the string).
peekCWString :: CWString -> IO String Source
Marshal a NUL terminated C wide string into a Haskell string.
peekCWStringLen :: CWStringLen -> IO String Source
Marshal a C wide string with explicit length into a Haskell string.
newCWString :: String -> IO CWString Source
Marshal a Haskell string into a NUL terminated C wide string.
free
or finalizerFree
.newCWStringLen :: String -> IO CWStringLen Source
Marshal a Haskell string into a C wide string (ie, wide character array) with explicit length information.
free
or finalizerFree
.withCWString :: String -> (CWString -> IO a) -> IO a Source
Marshal a Haskell string into a NUL terminated C wide string using temporary storage.
withCWStringLen :: String -> (CWStringLen -> IO a) -> IO a Source
Marshal a Haskell string into a C wide string (i.e. wide character array) in temporary storage, with explicit length information.
© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/8.2.1/docs/html/libraries/base-4.10.0.0/Foreign-C-String.html