text-1.2.1.3: An efficient packed Unicode text type.

Copyright | (c) 2008, 2009 Tom Harper, (c) 2009, 2010 Bryan O'Sullivan, (c) 2009 Duncan Coutts
License | BSD-style
Maintainer | bos@serpentine.com
Stability | experimental
Portability | GHC
Safe Haskell | None
Language | Haskell98

Data.Text.Internal

Contents

- Types
- Construction
- Safety
- Code that must be here for accessibility
- Utilities
- Checked multiplication
- Debugging

Description

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!

Synopsis

- data Text = Text !Array !Int !Int
- text :: Array -> Int -> Int -> Text
- textP :: Array -> Int -> Int -> Text
- safe :: Char -> Char
- empty :: Text
- empty_ :: Text
- firstf :: (a -> c) -> Maybe (a, b) -> Maybe (c, b)
- mul :: Int -> Int -> Int
- mul32 :: Int32 -> Int32 -> Int32
- mul64 :: Int64 -> Int64 -> Int64
- showText :: Text -> String

# Types

Internally, the `Text` type is represented as an array of `Word16` UTF-16 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-16 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, '�').
- A leading (or "high") surrogate code unit (0xD800–0xDBFF) must always be followed by a trailing (or "low") surrogate code unit (0xDC00-0xDFFF). A trailing surrogate code unit must always be preceded by a leading surrogate code unit.

data Text

A space efficient, packed, unboxed Unicode text type.

Constructors

Text !Array !Int !Int |

Instances

type Item Text = Char |

# Construction

text :: Array -> Int -> Int -> Text

Construct a `Text` without invisibly pinning its byte array in memory if its length has dwindled to zero.

textP :: Array -> Int -> Int -> Text

Deprecated: Use text instead

# Safety

safe :: Char -> Char

Map a `Char` to a `Text`-safe value.

UTF-16 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`.

empty_ :: Text

A non-inlined version of `empty`.

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

Checked multiplication. Calls `error` if the result would overflow.

mul32 :: Int32 -> Int32 -> Int32 infixl 7

Checked multiplication. Calls `error` if the result would overflow.

mul64 :: Int64 -> Int64 -> Int64 infixl 7

Checked multiplication. Calls `error` if the result would overflow.

# Debugging

showText :: Text -> String

A useful `show`-like function for debugging purposes.