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

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.