Community
Modules 50

Data.Text.Internal

License : BSD-style Maintainer : bos@serpentine.com Stability : experimental Portability : GHC

A module containing private Text internals. This exposes the Text representation and low level construction functions. Modules which extend the Text system may need to use this module.

You should not use this module unless you are determined to monkey with the internals, as the functions here do just about nothing to preserve data invariants. You have been warned!

Types

Internally, the Text type is represented as an array of Word8 UTF-8 code units. The offset and length fields in the constructor are in these units, not units of Char.

Invariants that all functions must maintain:

  • Since the Text type uses UTF-8 internally, it cannot represent characters in the reserved surrogate code point range U+D800 to U+DFFF. To maintain this invariant, the safe function maps Char values in this range to the replacement character (U+FFFD, '�').

  • Offset and length must point to a valid UTF-8 sequence of bytes. Violation of this may cause memory access violation and divergence.

data Text

A space efficient, packed, unboxed Unicode text type.

Text :: A.Array -> Int -> Int -> Text

A.Array

bytearray encoded as UTF-8

Int

offset in bytes (not in Char!), pointing to a start of UTF-8 sequence

Int

length in bytes (not in Char!), pointing to an end of UTF-8 sequence

type StrictText = Text

Type synonym for the strict flavour of Text.

Construction

text :: A.Array -> Int -> Int -> Text

Construct a Text without invisibly pinning its byte array in memory if its length has dwindled to zero. It ensures that empty Text values are shared.

A.Array

bytearray encoded as UTF-8

Int

offset in bytes (not in Char!), pointing to a start of UTF-8 sequence

Int

length in bytes (not in Char!), pointing to an end of UTF-8 sequence

textP :: A.Array -> Int -> Int -> Text

Use text instead

Safety

safe :: Char -> Char

Map a Char to a Text-safe value.

Unicode Surrogate code points are not included in the set of Unicode scalar values, but are unfortunately admitted as valid Char values by Haskell. They cannot be represented in a Text. This function remaps those code points to the Unicode replacement character (U+FFFD, '�'), and leaves other code points unchanged.

Code that must be here for accessibility

empty :: Text

O(1) The empty Text.

append :: Text -> Text -> Text

O(n) Appends one Text to the other by copying both of them into a new Text.

Utilities

firstf :: (a -> c) -> Maybe (a, b) -> Maybe (c, b)

Apply a function to the first element of an optional pair.

Checked multiplication

mul :: Int -> Int -> Int

Checked multiplication. Calls error if the result would overflow.

mul32 :: Int32 -> Int32 -> Int32

Checked multiplication. Calls error if the result would overflow.

mul64 :: Int64 -> Int64 -> Int64

Checked multiplication. Calls error if the result would overflow.

Debugging

showText :: Text -> String

A useful show-like function for debugging purposes.

Conversions

pack :: String -> Text

O(n) Convert a String into a Text. Performs replacement on invalid scalar values, so unpack . pack is not id:

>>> Data.Text.unpack (pack "\55555")
"\65533"
Copyright
(c) 2008, 2009 Tom Harper, (c) 2009, 2010 Bryan O'Sullivan, (c) 2009 Duncan Coutts
Build record and source files

Community 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

Import a package

Enter a package name and an exact version from Hackage. The site contains imported versions only.