| Copyright | (c) 2009 2010 Bryan O'Sullivan |
|---|---|
| License | BSD-style |
| Maintainer | bos@serpentine.com |
| Portability | GHC |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Data.Text.Foreign
Description
Support for using Text data with native code via the Haskell
foreign function interface.
Synopsis
- data I8
- fromPtr :: Ptr Word8 -> I8 -> IO Text
- fromPtr0 :: Ptr Word8 -> IO Text
- useAsPtr :: Text -> (Ptr Word8 -> I8 -> IO a) -> IO a
- asForeignPtr :: Text -> IO (ForeignPtr Word8, I8)
- withCString :: Text -> (CString -> IO a) -> IO a
- peekCStringLen :: CStringLen -> IO Text
- withCStringLen :: Text -> (CStringLen -> IO a) -> IO a
- lengthWord8 :: Text -> Int
- unsafeCopyToPtr :: Text -> Ptr Word8 -> IO ()
- dropWord8 :: I8 -> Text -> Text
- takeWord8 :: I8 -> Text -> Text
Interoperability with native code
The Text type is implemented using arrays that are not guaranteed
to have a fixed address in the Haskell heap. All communication with
native code must thus occur by copying data back and forth.
The Text type's internal representation is UTF-8.
To interoperate with native libraries that use different
internal representations, such as UTF-16 or UTF-32, consider using
the functions in the Encoding module.
A type representing a number of UTF-8 code units.
Since: text-2.0
Safe conversion functions
useAsPtr :: Text -> (Ptr Word8 -> I8 -> IO a) -> IO a Source #
O(n) Perform an action on a temporary, mutable copy of a
Text. The copy is freed as soon as the action returns.
asForeignPtr :: Text -> IO (ForeignPtr Word8, I8) Source #
O(n) Make a mutable copy of a Text.
Encoding as UTF-8
withCString :: Text -> (CString -> IO a) -> IO a Source #
Marshal a Text into a C string with a trailing NUL byte,
encoded as UTF-8 in temporary storage.
The temporary storage 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 function returns.
Since: text-2.0.1
peekCStringLen :: CStringLen -> IO Text Source #
O(n) Decode a C string with explicit length, which is assumed
to have been encoded as UTF-8. If decoding fails, a
UnicodeException is thrown.
Since: text-1.0.0.0
withCStringLen :: Text -> (CStringLen -> IO a) -> IO a Source #
Marshal a Text into a C string encoded as UTF-8 in temporary
storage, with explicit length information. The encoded string may
contain NUL bytes, and is not followed by a trailing NUL byte.
The temporary storage 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 function returns.
Since: text-1.0.0.0
Unsafe conversion code
lengthWord8 :: Text -> Int Source #
O(1) Return the length of a Text in units of Word8. This
is useful for sizing a target array appropriately before using
unsafeCopyToPtr.
Since: text-2.0
Low-level manipulation
Foreign functions that use UTF-8 internally may return indices in
units of Word8 instead of characters. These functions may
safely be used with such indices, as they will adjust offsets if
necessary to preserve the validity of a Unicode string.