text-1.1.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 | Trustworthy
Language | Haskell98

Data.Text.Lazy.Builder

Contents

- The Builder type
- Constructing Builders
- Flushing the buffer state

Description

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. Or, equivalently, prefer

    singleton 'a' <> singleton 'b' <> singleton 'c'

since the `<>` from recent versions of `Monoid` associates to the right.

Synopsis

- data Builder
- toLazyText :: Builder -> Text
- toLazyTextWith :: Int -> Builder -> Text
- singleton :: Char -> Builder
- fromText :: Text -> Builder
- fromLazyText :: Text -> Builder
- fromString :: String -> Builder
- flush :: Builder

# 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`.