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 | None |
Language | Haskell98 |
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.
- 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
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
.
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
O(1). Pop the strict Text
we have constructed so far, if any,
yielding a new chunk in the result lazy Text
.
Internal functions
ensureFree :: Int -> Builder Source #
Ensure that there are at least n
many elements available.