Data.Text.Builder.Linear

text-builder-linear-0.1.3: Builder for Text and ByteString based on linear types

Copyright | (c) 2022 Andrew Lelechenko
License | BSD3
Maintainer | Andrew Lelechenko <andrew.lelechenko@gmail.com>
Safe Haskell | None
Language | GHC2021

Data.Text.Builder.Linear

Description

Builder for strict `Text` and `ByteString`, based on linear types. It consistently outperforms Data.Text.Lazy.Builder from `text` as well as a strict builder from `text-builder`, and scales better.

Synopsis

- newtype Builder = Builder {
  - unBuilder :: Buffer %1 -> Buffer
  }
- runBuilder :: forall (m :: Multiplicity). Builder %m -> Text
- runBuilderBS :: forall (m :: Multiplicity). Builder %m -> ByteString
- fromText :: Text -> Builder
- fromChar :: Char -> Builder
- fromAddr :: Addr# -> Builder
- fromDec :: (Integral a, FiniteBits a) => a -> Builder
- fromUnboundedDec :: Integral a => a -> Builder
- fromHex :: (Integral a, FiniteBits a) => a -> Builder
- fromDouble :: Double -> Builder

# Documentation

newtype Builder #

Thin wrapper over `Buffer` with a handy `Semigroup` instance.

    >>> :set -XOverloadedStrings -XMagicHash
    >>> fromText "foo" <> fromChar '_' <> fromAddr "bar"#
    "foo_bar"

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.

Note that (similar to other builders) concatenation of `Builder`s allocates thunks. This is to a certain extent mitigated by aggressive inlining, but it is faster to use `Buffer` directly.

Constructors

Builder |
Fields unBuilder :: Buffer %1 -> Buffer

#### Instances

Instances details

Monoid Builder # |
Instance details Defined in Data.Text.Builder.Linear Methods mempty :: Builder # mappend :: Builder -> Builder -> Builder # mconcat :: [Builder] -> Builder #
Semigroup Builder # |
Instance details Defined in Data.Text.Builder.Linear Methods (<>) :: Builder -> Builder -> Builder # sconcat :: NonEmpty Builder -> Builder # stimes :: Integral b => b -> Builder -> Builder #
IsString Builder # | Use `fromString` to create `Builder` from `String`.
Instance details Defined in Data.Text.Builder.Linear Methods fromString :: String -> Builder #
Show Builder # |
Instance details Defined in Data.Text.Builder.Linear Methods showsPrec :: Int -> Builder -> ShowS # show :: Builder -> String # showList :: [Builder] -> ShowS #

runBuilder :: forall (m :: Multiplicity). Builder %m -> Text #

Run `Builder` computation on an empty `Buffer`, returning strict `Text`.

    >>> :set -XOverloadedStrings -XMagicHash
    >>> runBuilder (fromText "foo" <> fromChar '_' <> fromAddr "bar"#)
    "foo_bar"

This function has a polymorphic arrow and thus can be used both in usual and linear contexts.

runBuilderBS :: forall (m :: Multiplicity). Builder %m -> ByteString #

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

fromText :: Text -> Builder #

Create `Builder`, containing a given `Text`.

    >>> :set -XOverloadedStrings
    >>> fromText "foo" <> fromText "bar"
    "foobar"

For literal strings it is faster to use `fromAddr` instead of `fromText`.

fromChar :: Char -> Builder #

Create `Builder`, containing a given `Char`.

    >>> fromChar 'x' <> fromChar 'y'
    "xy"

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

fromAddr :: Addr# -> Builder #

Create `Builder`, containing a null-terminated UTF-8 string, specified by `Addr#`.

    >>> :set -XMagicHash
    >>> fromAddr "foo"# <> fromAddr "bar"#
    "foobar"

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

fromDec :: (Integral a, FiniteBits a) => a -> Builder #

Create `Builder`, containing decimal representation of a given bounded integer.

    >>> fromChar 'x' <> fromDec (123 :: Int)
    "x123"

fromUnboundedDec :: Integral a => a -> Builder #

Create `Builder`, containing decimal representation of a given unbounded integer.

    >>> fromChar 'x' <> fromUnboundedDec (1e24 :: Integer)
    "x1000000000000000000000000"

Since: 0.1.3

fromHex :: (Integral a, FiniteBits a) => a -> Builder #

Create `Builder`, containing hexadecimal representation of a given integer.

    >>> :set -XMagicHash
    >>> fromAddr "0x"# <> fromHex (0x123def :: Int)
    "0x123def"

fromDouble :: Double -> Builder #

Create `Builder`, containing decimal representation of a given `Double`.

    >>> :set -XMagicHash
    >>> fromAddr "pi="# <> fromDouble pi
    "pi=3.141592653589793"