Copyright	(c) The FFI task force 2001
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	ffi@haskell.org
Stability	provisional
Portability	portable
Safe Haskell	Trustworthy
Language	Haskell2010

Foreign.C.String

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
castCharToCUChar :: Char -> CUChar
castCUCharToChar :: CUChar -> Char
castCharToCSChar :: Char -> CSChar
castCSCharToChar :: CSChar -> 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 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).

Using a locale-dependent encoding

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.

the Haskell string may not contain any NUL characters
new storage is allocated for the C string and must be explicitly freed using free or finalizerFree.

newCStringLen :: String -> IO CStringLen Source #

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 free or finalizerFree.

withCString :: String -> (CString -> IO a) -> IO a Source #

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 Source #

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 Source #

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 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.

the Haskell string may not contain any NUL characters
new storage is allocated for the C string and must be explicitly freed using free or finalizerFree.

newCAStringLen :: String -> IO CStringLen Source #

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 free or finalizerFree.

withCAString :: String -> (CString -> IO a) -> IO a Source #

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 Source #

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.

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 201706L), or
UTF-16 (as used on Windows systems).

type 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 CWchars 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.

the Haskell string may not contain any NUL characters
new storage is allocated for the C wide string and must be explicitly freed using 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.

new storage is allocated for the C wide string and must be explicitly freed using 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.

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 Source #

Marshal a Haskell string into a C wide string (i.e. wide 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.