Documentation

Internally Buffer is a mutable buffer. If a client gets hold of a variable of type Buffer, they'd be able to pass a mutable buffer to concurrent threads. That's why API below is carefully designed to prevent such possibility: clients always work with linear functions Buffer ⊸ Buffer instead and run them on an empty Buffer to extract results.

In terms of linear-base Buffer is Consumable (see consumeBuffer) and Dupable (see dupBuffer), but not Movable.

>>> :set -XOverloadedStrings -XLinearTypes
>>> import Data.Text.Builder.Linear.Buffer
>>> runBuffer (\b -> '!' .<| "foo" <| (b |> "bar" |>. '.'))
"!foobar."

Remember: this is a strict builder, so on contrary to Data.Text.Lazy.Builder for optimal performance you should use strict left folds instead of lazy right ones.

Buffer is an unlifted datatype, so you can put it into an unboxed tuple (# ..., ... #), but not into (..., ...).

Run a linear function on an empty Buffer, producing a strict Text.

Be careful to write runBuffer (b -> ...) instead of runBuffer $ b -> ..., because current implementation of linear types lacks special support for ($). Another option is to enable {-# LANGUAGE BlockArguments #-} and write runBuffer b -> .... Alternatively, you can import ($) from linear-base.

runBuffer is similar in spirit to mutable arrays API in Data.Array.Mutable.Linear, which provides functions like fromList ∷ [a] → (Vector a ⊸ Ur b) ⊸ Ur b. Here the initial buffer is always empty and b is Text. Since Text is Movable, Text and Ur Text are equivalent.

Same as runBuffer, but returning a UTF-8 encoded strict ByteString.

Duplicate builder. Feel free to process results in parallel threads. Similar to Dupable from linear-base.

It is a bit tricky to use because of current limitations of linear types with regards to let and where. E. g., one cannot write

let (# b1, b2 #) = dupBuffer b in ("foo" <| b1) >< (b2 |> "bar")

Instead write:

>>> :set -XOverloadedStrings -XLinearTypes -XUnboxedTuples
>>> import Data.Text.Builder.Linear.Buffer
>>> runBuffer (\b -> (\(# b1, b2 #) -> ("foo" <| b1) >< (b2 |> "bar")) (dupBuffer b))
"foobar"

Note the unboxed tuple: Buffer is an unlifted datatype, so it cannot be put into (..., ...).

Consume buffer linearly, similar to Consumable from linear-base.

Erase buffer's content, replacing it with an empty Text.

This is just a normal foldl', but with a linear arrow and unlifted accumulator.

Append Text suffix to a Buffer by mutating it. If a suffix is statically known, consider using (|>#) for optimal performance.

>>> :set -XOverloadedStrings -XLinearTypes
>>> runBuffer (\b -> b |> "foo" |> "bar")
"foobar"

Append Char to a Buffer by mutating it.

>>> :set -XLinearTypes
>>> runBuffer (\b -> b |>. 'q' |>. 'w')
"qw"

In contrast to singleton, it's a responsibility of the caller to sanitize surrogate code points with safe.

Append a null-terminated UTF-8 string to a Buffer by mutating it. E. g.,

>>> :set -XOverloadedStrings -XLinearTypes -XMagicHash
>>> runBuffer (\b -> b |># "foo"# |># "bar"#)
"foobar"

The literal string must not contain zero bytes \0 and must be a valid UTF-8, these conditions are not checked.

Note the inconsistency in naming: unfortunately, GHC parser does not allow for #<|.

Prepend Text prefix to a Buffer by mutating it. If a prefix is statically known, consider using (<|#) for optimal performance.

>>> :set -XOverloadedStrings -XLinearTypes
>>> runBuffer (\b -> "foo" <| "bar" <| b)
"foobar"

Prepend Char to a Buffer by mutating it.

>>> :set -XLinearTypes
>>> runBuffer (\b -> 'q' .<| 'w' .<| b)
"qw"

In contrast to singleton, it's a responsibility of the caller to sanitize surrogate code points with safe.

Prepend a null-terminated UTF-8 string to a Buffer by mutating it. E. g.,

>>> :set -XOverloadedStrings -XLinearTypes -XMagicHash
>>> runBuffer (\b -> "foo"# <|# "bar"# <|# b)
"foobar"

The literal string must not contain zero bytes \0 and must be a valid UTF-8, these conditions are not checked.

Concatenate two Buffers, potentially mutating both of them.

You likely need to use dupBuffer to get hold on two builders at once:

>>> :set -XOverloadedStrings -XLinearTypes -XUnboxedTuples
>>> import Data.Text.Builder.Linear.Buffer
>>> runBuffer (\b -> (\(# b1, b2 #) -> ("foo" <| b1) >< (b2 |> "bar")) (dupBuffer b))
"foobar"

Append decimal number.

Prepend decimal number.

Append double.

Prepend double

Append hexadecimal number.

Prepend hexadecimal number.

Append given number of spaces.

Prepend given number of spaces.