Data.Text.Foreign

text-1.2.4.1: An efficient packed Unicode text type.

Copyright | (c) 2009 2010 Bryan O'Sullivan
License | BSD-style
Maintainer | bos@serpentine.com
Portability | GHC
Safe Haskell | None
Language | Haskell2010

Data.Text.Foreign

Contents

- Interoperability with native code
- Safe conversion functions
  - Encoding as UTF-8
- 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)
- peekCStringLen :: CStringLen -> IO Text
- withCStringLen :: Text -> (CStringLen -> IO a) -> IO a
- 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 Source #

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

#### Instances

Instances details

Bounded I16 # |
Instance details Defined in Data.Text.Foreign Methods minBound :: I16 Source # maxBound :: I16 Source #
Enum I16 # |
Instance details Defined in Data.Text.Foreign Methods succ :: I16 -> I16 Source # pred :: I16 -> I16 Source # toEnum :: Int -> I16 Source # fromEnum :: I16 -> Int Source # enumFrom :: I16 -> [I16] Source # enumFromThen :: I16 -> I16 -> [I16] Source # enumFromTo :: I16 -> I16 -> [I16] Source # enumFromThenTo :: I16 -> I16 -> I16 -> [I16] Source #
Eq I16 # |
Instance details Defined in Data.Text.Foreign Methods (==) :: I16 -> I16 -> Bool Source # (/=) :: I16 -> I16 -> Bool Source #
Integral I16 # |
Instance details Defined in Data.Text.Foreign Methods quot :: I16 -> I16 -> I16 Source # rem :: I16 -> I16 -> I16 Source # div :: I16 -> I16 -> I16 Source # mod :: I16 -> I16 -> I16 Source # quotRem :: I16 -> I16 -> (I16, I16) Source # divMod :: I16 -> I16 -> (I16, I16) Source # toInteger :: I16 -> Integer Source #
Num I16 # |
Instance details Defined in Data.Text.Foreign Methods (+) :: I16 -> I16 -> I16 Source # (-) :: I16 -> I16 -> I16 Source # (*) :: I16 -> I16 -> I16 Source # negate :: I16 -> I16 Source # abs :: I16 -> I16 Source # signum :: I16 -> I16 Source # fromInteger :: Integer -> I16 Source #
Ord I16 # |
Instance details Defined in Data.Text.Foreign Methods compare :: I16 -> I16 -> Ordering Source # (<) :: I16 -> I16 -> Bool Source # (<=) :: I16 -> I16 -> Bool Source # (>) :: I16 -> I16 -> Bool Source # (>=) :: I16 -> I16 -> Bool Source # max :: I16 -> I16 -> I16 Source # min :: I16 -> I16 -> I16 Source #
Read I16 # |
Instance details Defined in Data.Text.Foreign Methods readsPrec :: Int -> ReadS I16 Source # readList :: ReadS [I16] Source # readPrec :: ReadPrec I16 Source # readListPrec :: ReadPrec [I16] Source #
Real I16 # |
Instance details Defined in Data.Text.Foreign Methods toRational :: I16 -> Rational Source #
Show I16 # |
Instance details Defined in Data.Text.Foreign Methods showsPrec :: Int -> I16 -> ShowS Source # show :: I16 -> String Source # showList :: [I16] -> ShowS Source #

# Safe conversion functions

fromPtr Source #

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

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

## Encoding as UTF-8

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

lengthWord16 :: Text -> Int Source #

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 () Source #

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 Source #

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 Source #

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.