text-2.0.2: An efficient packed Unicode text type.

Copyright | (c) 2013 Bryan O'Sullivan (c) 2010 Johan Tibell
License | BSD-style (see LICENSE)
Maintainer | Johan Tibell <johan.tibell@gmail.com>
Stability | experimental
Portability | portable to Hugs and GHC
Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.Text.Internal.Builder

Contents

- Public API
  - The Builder type
  - Constructing Builders
  - Flushing the buffer state
- Internal functions

Description

Warning: this is an internal module, and does not have a stable API or name. Functions in this module may not check or enforce preconditions expected by public modules. Use at your own risk!

Efficient construction of lazy `Text` values. The principal operations on a `Builder` are `singleton`, `fromText`, and `fromLazyText`, which construct new builders, and `mappend`, which concatenates two builders.

To get maximum performance when building lazy `Text` values using a builder, associate `mappend` calls to the right. For example, prefer

    singleton 'a' `mappend` (singleton 'b' `mappend` singleton 'c')

to

    singleton 'a' `mappend` singleton 'b' `mappend` singleton 'c'

as the latter associates `mappend` to the left.

Synopsis

- data Builder
- toLazyText :: Builder -> Text
- toLazyTextWith :: Int -> Builder -> Text
- singleton :: Char -> Builder
- fromText :: Text -> Builder
- fromLazyText :: Text -> Builder
- fromString :: String -> Builder
- flush :: Builder
- append' :: Builder -> Builder -> Builder
- ensureFree :: Int -> Builder
- writeN :: Int -> (forall s. MArray s -> Int -> ST s ()) -> Builder

# Public API

## The Builder type

data Builder Source #

A `Builder` is an efficient way to build lazy `Text` values. There are several functions for constructing builders, but only one to inspect them: to extract any data, you have to turn them into lazy `Text` values using `toLazyText`.

Internally, a builder constructs a lazy `Text` by filling arrays piece by piece. As each buffer is filled, it is 'popped' off, to become a new chunk of the resulting lazy `Text`. All this is hidden from the user of the `Builder`.

#### Instances

Instances details

IsString Builder Source #

Performs replacement on invalid scalar values:

    >>> :set -XOverloadedStrings
    >>> "\55555" :: Builder
    "\65533"

Instance details Defined in Data.Text.Internal.Builder Methods fromString :: String -> Builder Source #
Monoid Builder Source # |
Instance details Defined in Data.Text.Internal.Builder Methods mempty :: Builder Source # mappend :: Builder -> Builder -> Builder Source # mconcat :: [Builder] -> Builder Source #
Semigroup Builder Source # |
Instance details Defined in Data.Text.Internal.Builder Methods (<>) :: Builder -> Builder -> Builder Source # sconcat :: NonEmpty Builder -> Builder Source # stimes :: Integral b => b -> Builder -> Builder Source #
Show Builder Source # |
Instance details Defined in Data.Text.Internal.Builder Methods showsPrec :: Int -> Builder -> ShowS Source # show :: Builder -> String Source # showList :: [Builder] -> ShowS Source #
Eq Builder Source # |
Instance details Defined in Data.Text.Internal.Builder Methods (==) :: Builder -> Builder -> Bool Source # (/=) :: Builder -> Builder -> Bool Source #
Ord Builder Source # |
Instance details Defined in Data.Text.Internal.Builder Methods compare :: Builder -> Builder -> Ordering Source # (<) :: Builder -> Builder -> Bool Source # (<=) :: Builder -> Builder -> Bool Source # (>) :: Builder -> Builder -> Bool Source # (>=) :: Builder -> Builder -> Bool Source # max :: Builder -> Builder -> Builder Source # min :: Builder -> Builder -> Builder Source #

toLazyText :: Builder -> Text Source #

O(n). Extract a lazy `Text` from a `Builder` with a default buffer size. The construction work takes place if and when the relevant part of the lazy `Text` is demanded.

toLazyTextWith :: Int -> Builder -> Text Source #

O(n). Extract a lazy `Text` from a `Builder`, using the given size for the initial buffer. The construction work takes place if and when the relevant part of the lazy `Text` is demanded.

If the initial buffer is too small to hold all data, subsequent buffers will be the default buffer size.

## Constructing Builders

singleton :: Char -> Builder Source #

O(1). A `Builder` taking a single character, satisfying

-     toLazyText (singleton c) = singleton c

fromText :: Text -> Builder Source #

O(1). A `Builder` taking a `Text`, satisfying

-     toLazyText (fromText t) = fromChunks [t]

fromLazyText :: Text -> Builder Source #

O(1). A `Builder` taking a lazy `Text`, satisfying

-     toLazyText (fromLazyText t) = t

fromString :: String -> Builder Source #

O(1). A Builder taking a `String`, satisfying

-     toLazyText (fromString s) = fromChunks [S.pack s]

Performs replacement on invalid scalar values:

    >>> fromString "\55555"
    "\65533"

Since: text-1.2.0.0

## Flushing the buffer state

flush :: Builder Source #

O(1). Pop the strict `Text` we have constructed so far, if any, yielding a new chunk in the result lazy `Text`.

# Internal functions

append' :: Builder -> Builder -> Builder Source #

ensureFree :: Int -> Builder Source #

Ensure that there are at least `n` many elements available.

writeN :: Int -> (forall s. MArray s -> Int -> ST s ()) -> Builder Source #

Ensure that `n` many elements are available, and then use `f` to write some elements into the memory.