Community
Modules 50

Data.Text.Internal.Builder

Maintainer : Johan Tibell <johan.tibell@gmail.com> Stability : experimental Portability : portable to Hugs and GHC

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.

Public API

** The Builder type

newtype 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.

toLazyText :: Builder -> L.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 -> L.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 :: S.Text -> Builder

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

  • toLazyText (fromText t) = fromChunks [t]

fromLazyText :: L.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]

Performs replacement on invalid scalar values:

>>> fromString "\55555"
"\65533"

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. A.MArray s -> Int -> ST s ()) -> Builder

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

Instances

6
  • instance Semigroup Builder
  • instance Monoid Builder
  • instance String.IsString Builder

    Performs replacement on invalid scalar values:

    >>> :set -XOverloadedStrings
    >>> "\55555" :: Builder
    "\65533"
    
  • instance Show Builder
  • instance Eq Builder
  • instance Ord Builder
Copyright
(c) 2013 Bryan O'Sullivan (c) 2010 Johan Tibell
License
BSD-style (see LICENSE)
Build record and source files

Community contribution. The service has not verified this documentation. The generator reported 2 diagnostics.

Target: Linux on x86-64. Some inferred types and resolved links are not available.

Generator: aihc-haddock-858b1951-web-1

Metadata snapshot: 0b0724abd14577f7a6c8172d62e3e1c0808feb114d4d379402e17f37e3c7801e

Open the dependency plan · Download the documentation model

Import a package

Enter a package name and an exact version from Hackage. The site contains imported versions only.