Data.Text.Internal.Builder

text-1.2.1.3: An efficient packed Unicode text type.

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

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

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

Eq Builder |
Ord Builder |
Show Builder |
IsString Builder |
Monoid Builder |

toLazyText :: Builder -> Text

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

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

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

-     toLazyText (singleton c) = singleton c

fromText :: Text -> Builder

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

-     toLazyText (fromText t) = fromChunks [t]

fromLazyText :: Text -> Builder

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

-     toLazyText (fromLazyText t) = t

fromString :: String -> Builder

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

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

## Flushing the buffer state

flush :: Builder

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

ensureFree :: Int -> Builder

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

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

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