Data.Text.Builder.Linear.Buffer

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 ∷ Movable b ⇒ [a] → (Array a ⊸ b) ⊸ b. Here the initial buffer is always empty and b is Text.

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 -> case dupBuffer b of (# b1, b2 #) -> ("foo" <| b1) >< (b2 |> "bar"))"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 Data.List.foldl', but with a linear arrow and unlifted accumulator.

Create an empty Buffer.

The first Buffer is the input and the second is a new empty Buffer.

This function is needed in some situations, e.g. with justifyRight. The following example creates a utility function that justify a text and then append it to a buffer.

>>> :set -XOverloadedStrings -XLinearTypes -XUnboxedTuples>>> import Data.Text.Builder.Linear.Buffer>>> import Data.Text (Text)>>> :{appendJustified :: Buffer %1 -> Text -> BufferappendJustified b t = case newEmptyBuffer b of  -- Note that we need to create a new buffer from the text, in order  -- to justify only the text and not the input buffer.  (# b', empty #) -> b' >< justifyRight 12 ' ' (empty |> t):}

>>> runBuffer (\b -> (b |> "Test:") `appendJustified` "AAA" `appendJustified` "BBBBBBB")"Test:         AAA     BBBBBBB"

Note: a previous buffer is necessary in order to create an empty buffer with the same pinnedness.

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 -> case dupBuffer b of (# b1, b2 #) -> ("foo" <| b1) >< (b2 |> "bar"))"foobar"

Append Char to a Buffer by mutating it.

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

Warning: In contrast to singleton, it is the responsibility of the caller to sanitize surrogate code points with safe.

Prepend Char to a Buffer by mutating it.

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

Warning: In contrast to singleton, it is the responsibility of the caller to sanitize surrogate code points with safe.

Pad a builder from the right side to the specified length with the specified character.

>>> :set -XLinearTypes>>> runBuffer (\b -> justifyLeft 10 'x' (appendChars 3 'A' b))"AAAxxxxxxx">>> runBuffer (\b -> justifyLeft 5 'x' (appendChars 6 'A' b))"AAAAAA"

Note that newEmptyBuffer is needed in some situations. See justifyRight for an example.

Warning: In contrast to singleton, it is the responsibility of the caller to sanitize surrogate code points with safe.

Pad a builder from the left side to the specified length with the specified character.

>>> :set -XLinearTypes>>> runBuffer (\b -> justifyRight 10 'x' (appendChars 3 'A' b))"xxxxxxxAAA">>> runBuffer (\b -> justifyRight 5 'x' (appendChars 6 'A' b))"AAAAAA"

Note that newEmptyBuffer is needed in some situations. The following example creates a utility function that justify a text and then append it to a buffer.

>>> :set -XOverloadedStrings -XLinearTypes -XUnboxedTuples>>> import Data.Text.Builder.Linear.Buffer>>> import Data.Text (Text)>>> :{appendJustified :: Buffer %1 -> Text -> BufferappendJustified b t = case newEmptyBuffer b of  -- Note that we need to create a new buffer from the text, in order  -- to justify only the text and not the input buffer.  (# b', empty #) -> b' >< justifyRight 12 ' ' (empty |> t):}

>>> runBuffer (\b -> (b |> "Test:") `appendJustified` "AAA" `appendJustified` "BBBBBBB")"Test:         AAA     BBBBBBB"

Warning: In contrast to singleton, it is the responsibility of the caller to sanitize surrogate code points with safe.

Center a builder to the specified length with the specified character.

>>> :set -XLinearTypes>>> runBuffer (\b -> center 10 'x' (appendChars 3 'A' b))"xxxxAAAxxx">>> runBuffer (\b -> center 5 'x' (appendChars 6 'A' b))"AAAAAA"

Note that newEmptyBuffer is needed in some situations. See justifyRight for an example.

Warning: In contrast to singleton, it is the responsibility of the caller to sanitize surrogate code points with safe.