Data.Text.Lazy.Builder

text-1.2.3.0: 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>
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 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

Eq Builder Source # |
Instance details Methods (==) :: Builder -> Builder -> Bool Source # (/=) :: Builder -> Builder -> Bool Source #
Ord Builder Source # |
Instance details 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 #
Show Builder Source # |
Instance details Methods showsPrec :: Int -> Builder -> ShowS Source # show :: Builder -> String Source # showList :: [Builder] -> ShowS Source #
IsString Builder Source # |
Instance details Methods fromString :: String -> Builder Source #
Semigroup Builder Source # |
Instance details Methods (<>) :: Builder -> Builder -> Builder Source # sconcat :: NonEmpty Builder -> Builder Source # stimes :: Integral b => b -> Builder -> Builder Source #
Monoid Builder Source # |
Instance details Methods mempty :: Builder Source # mappend :: Builder -> Builder -> Builder Source # mconcat :: [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]

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