W3cubDocs

/Haskell 8

Data.Text.Foreign

Copyright (c) 2009 2010 Bryan O'Sullivan
License BSD-style
Maintainer [email protected]
Portability GHC
Safe Haskell None
Language Haskell98

Description

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

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
Bounded I16
Instance details

Defined in Data.Text.Foreign

Enum I16
Instance details

Defined in Data.Text.Foreign

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

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.

© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/8.6.1/docs/html/libraries/text-1.2.3.1/Data-Text-Foreign.html