base-4.6.0.1: Basic libraries

Portability | non-portable
Stability | internal
Maintainer | libraries@haskell.org
Safe Haskell | Trustworthy

GHC.Foreign

Contents

- C strings with a configurable encoding

Description

Foreign marshalling support for CStrings with configurable encodings

Synopsis

- peekCString :: TextEncoding -> CString -> IO String
- peekCStringLen :: TextEncoding -> CStringLen -> IO String
- newCString :: TextEncoding -> String -> IO CString
- newCStringLen :: TextEncoding -> String -> IO CStringLen
- withCString :: TextEncoding -> String -> (CString -> IO a) -> IO a
- withCStringLen :: TextEncoding -> String -> (CStringLen -> IO a) -> IO a
- charIsRepresentable :: TextEncoding -> Char -> IO Bool

# C strings with a configurable encoding

peekCString :: TextEncoding -> CString -> IO String

Marshal a NUL terminated C string into a Haskell string.

peekCStringLen :: TextEncoding -> CStringLen -> IO String

Marshal a C string with explicit length into a Haskell string.

newCString :: TextEncoding -> 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 :: TextEncoding -> 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 :: TextEncoding -> 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 :: TextEncoding -> 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 :: TextEncoding -> Char -> IO Bool

Determines whether a character can be accurately encoded in a `CString`.

Pretty much anyone who uses this function is in a state of sin because whether or not a character is encodable will, in general, depend on the context in which it occurs.