base-4.19.2.0: Core data structures and operations
Copyright(c) The University of Glasgow 2008-2011
Licensesee libraries/base/LICENSE
Maintainerlibraries@haskell.org
Stabilityinternal
Portabilitynon-portable
Safe HaskellTrustworthy
LanguageHaskell2010

GHC.Foreign

Description

Foreign marshalling support for CStrings with configurable encodings

Synopsis

C strings with a configurable encoding

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

Conversion of C strings into Haskell strings

peekCString :: TextEncoding -> CString -> IO String Source #

Marshal a NUL terminated C string into a Haskell string.

peekCStringLen :: TextEncoding -> CStringLen -> IO String Source #

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

Conversion of Haskell strings into C strings

newCString :: TextEncoding -> 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 :: TextEncoding -> String -> IO CStringLen Source #

Marshal a Haskell string into a C string (ie, character array) with explicit length information.

Note that this does not NUL terminate the resulting string.

  • new storage is allocated for the C string and must be explicitly freed using free or finalizerFree.

newCStringLen0 :: TextEncoding -> String -> IO CStringLen Source #

Marshal a Haskell string into a NUL-terminated 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.

Since: base-4.19.0.0

Conversion of Haskell strings into C strings using temporary storage

withCString :: TextEncoding -> 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 :: TextEncoding -> 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.

Note that this does not NUL terminate the resulting string.

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

withCStringLen0 :: TextEncoding -> String -> (CStringLen -> IO a) -> IO a Source #

Marshal a Haskell string into a NUL-terminated 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.

Since: base-4.19.0.0

withCStringsLen :: TextEncoding -> [String] -> (Int -> Ptr CString -> IO a) -> IO a Source #

Marshal a list of Haskell strings into an array of NUL terminated C strings using temporary storage.

  • the Haskell strings 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.

charIsRepresentable :: TextEncoding -> Char -> IO Bool Source #

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.