Foreign.C.String

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.

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

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

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

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

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 201103L), 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 free or 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 free or 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 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.