newtype I8
A type representing a number of UTF-8 code units.
License : BSD-style Maintainer : bos@serpentine.com Portability : GHC
Support for using Text data with native code via the Haskell
foreign function interface.
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.
newtype I8A type representing a number of UTF-8 code units.
fromPtr :: Ptr Word8 -> I8 -> IO TextO(n) Create a new Text from a Ptr Word8 by copying the
contents of the array.
This function is unsafe. The source array must contain a valid UTF-8 string of the given length. There are no guarantees about what happens otherwise.
source array
I8length of source array (in Word8 units)
fromPtr0 :: Ptr Word8 -> IO TextO(n) Create a new Text from a Ptr Word8 by copying the
contents of the NUL-terminated array.
This function is unsafe. The source array must contain a NULL-terminated valid UTF-8 string. There are no guarantees about what happens otherwise.
source array
useAsPtr :: Text -> (Ptr Word8 -> I8 -> IO a) -> IO aO(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)O(n) Make a mutable copy of a Text.
peekCString :: CString -> IO TextO(n) Decode a null-terminated C string, which is assumed
to have been encoded as UTF-8. If decoding fails, a
UnicodeException is thrown.
withCString :: Text -> (CString -> IO a) -> IO aMarshal a Text into a C string with a trailing NUL byte,
encoded as UTF-8 in temporary storage.
The Text itself must not contain any NUL bytes, this precondition
is not checked. Cf. withCStringLen.
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.
peekCStringLen :: CStringLen -> IO TextO(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.
withCStringLen :: Text -> (CStringLen -> IO a) -> IO aMarshal 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.
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.
dropWord8 :: I8 -> Text -> TextO(1) Return the suffix of the Text, with n Word8 units
dropped from its beginning.
If n would cause the Text to begin inside a code point, the
beginning of the suffix will be advanced by several additional Word8
unit to maintain its validity.
takeWord8 :: I8 -> Text -> TextO(1) Return the prefix of the Text of n Word8 units in
length.
If n would cause the Text to end inside a code point, the
end of the prefix will be advanced by several additional Word8 units
to maintain its validity.
lengthWord8 :: Text -> IntO(1) Return the length of a Text in units of Word8. This
is useful for sizing a target array appropriately before using
unsafeCopyToPtr.
unsafeCopyToPtr :: Text -> Ptr Word8 -> 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.
instance Bounded I8instance Enum I8instance Eq I8instance Integral I8instance Num I8instance Ord I8instance Read I8instance Real I8instance Show I8Community contribution. The service has not verified this documentation. The generator reported 2 diagnostics.
Target: Linux on x86-64. Some inferred types and resolved links are not available.
Generator: aihc-haddock-858b1951-web-1
Metadata snapshot: 0b0724abd14577f7a6c8172d62e3e1c0808feb114d4d379402e17f37e3c7801e
Open the dependency plan · Download the documentation model