text-0.11.2.0: An efficient packed Unicode text type.

Portability | GHC
Stability | experimental
Maintainer | bos@serpentine.com, rtomharper@googlemail.com, duncan@haskell.org
Safe Haskell | None

Data.Text.Foreign

Contents

- Interoperability with native code
- Safe conversion functions
- Unsafe conversion code
- Low-level manipulation

Description

Support for using `Text` data with native code via the Haskell foreign function interface.

Synopsis

- data I16
- fromPtr :: Ptr Word16 -> I16 -> IO Text
- useAsPtr :: Text -> (Ptr Word16 -> I16 -> IO a) -> IO a
- asForeignPtr :: Text -> IO (ForeignPtr Word16, I16)
- lengthWord16 :: Text -> Int
- unsafeCopyToPtr :: Text -> Ptr Word16 -> IO ()
- dropWord16 :: I16 -> Text -> Text
- takeWord16 :: I16 -> 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-16, using the platform's native endianness. This makes copied data suitable for use with native libraries that use a similar representation, such as ICU. To interoperate with native libraries that use different internal representations, such as UTF-8 or UTF-32, consider using the functions in the `Encoding` module.

data I16

A type representing a number of UTF-16 code units.

Instances

Bounded I16 |
Enum I16 |
Eq I16 |
Integral I16 |
Num I16 |
Ord I16 |
Read I16 |
Real I16 |
Show I16 |

# Safe conversion functions

fromPtr

Arguments

:: Ptr Word16 | source array
-> I16 | length of source array (in `Word16` units)
-> IO Text |

O(n) Create a new `Text` from a `Ptr` `Word16` by copying the contents of the array.

useAsPtr :: Text -> (Ptr Word16 -> I16 -> IO a) -> IO a

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 Word16, I16)

O(n) Make a mutable copy of a `Text`.

# Unsafe conversion code

lengthWord16 :: Text -> Int

O(1) Return the length of a `Text` in units of `Word16`. This is useful for sizing a target array appropriately before using `unsafeCopyToPtr`.

unsafeCopyToPtr :: Text -> Ptr Word16 -> IO ()

O(n) Copy a `Text` to an array. The array is assumed to be big enough to hold the contents of the entire `Text`.

# Low-level manipulation

Foreign functions that use UTF-16 internally may return indices in units of `Word16` 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.

dropWord16 :: I16 -> Text -> Text

O(1) Return the suffix of the `Text`, with `n` `Word16` units dropped from its beginning.

If `n` would cause the `Text` to begin inside a surrogate pair, the beginning of the suffix will be advanced by one additional `Word16` unit to maintain its validity.

takeWord16 :: I16 -> Text -> Text

O(1) Return the prefix of the `Text` of `n` `Word16` units in length.

If `n` would cause the `Text` to end inside a surrogate pair, the end of the prefix will be advanced by one additional `Word16` unit to maintain its validity.