text-builder-1.0.0.4: Efficient and flexible strict text builder

Safe Haskell | None
Language | Haskell2010

TextBuilder

Contents

- Accessors
- Constructors
  - Transformations
  - Textual
  - Character
  - Integers
    - Decimal
    - Binary
    - Octal
    - Hexadecimal

Synopsis

- data TextBuilder
- toText :: TextBuilder -> Text
- toString :: TextBuilder -> String
- isEmpty :: TextBuilder -> Bool
- force :: TextBuilder -> TextBuilder
- intercalate :: Foldable f => TextBuilder -> f TextBuilder -> TextBuilder
- intercalateMap :: Foldable f => TextBuilder -> (a -> TextBuilder) -> f a -> TextBuilder
- text :: Text -> TextBuilder
- lazyText :: Text -> TextBuilder
- string :: String -> TextBuilder
- unsafeUtf8ByteString :: ByteString -> TextBuilder
- char :: Char -> TextBuilder
- unicodeCodepoint :: Int -> TextBuilder
- decimal :: Integral a => a -> TextBuilder
- fixedLengthDecimal :: Integral a => Int -> a -> TextBuilder
- thousandSeparatedDecimal :: Integral a => Char -> a -> TextBuilder
- binary :: FiniteBits a => a -> TextBuilder
- prefixedBinary :: FiniteBits a => a -> TextBuilder
- octal :: (FiniteBits a, Integral a) => a -> TextBuilder
- prefixedOctal :: (FiniteBits a, Integral a) => a -> TextBuilder
- hexadecimal :: (FiniteBits a, Integral a) => a -> TextBuilder
- prefixedHexadecimal :: (FiniteBits a, Integral a) => a -> TextBuilder

# Documentation

data TextBuilder Source #

Composable specification of how to efficiently construct strict `Text`.

Provides instances of `Semigroup` and `Monoid`, which have complexity of O(1).

#### Instances

Instances details

Arbitrary TextBuilder |
Instance details Defined in TextBuilderCore Methods arbitrary :: Gen TextBuilder shrink :: TextBuilder -> [TextBuilder]
Monoid TextBuilder |
Instance details Defined in TextBuilderCore Methods mempty :: TextBuilder Source # mappend :: TextBuilder -> TextBuilder -> TextBuilder Source # mconcat :: [TextBuilder] -> TextBuilder Source #
Semigroup TextBuilder |
Instance details Defined in TextBuilderCore Methods (<>) :: TextBuilder -> TextBuilder -> TextBuilder Source # sconcat :: NonEmpty TextBuilder -> TextBuilder Source # stimes :: Integral b => b -> TextBuilder -> TextBuilder Source #
IsString TextBuilder |
Instance details Defined in TextBuilderCore Methods fromString :: String -> TextBuilder Source #
Show TextBuilder |
Instance details Defined in TextBuilderCore Methods showsPrec :: Int -> TextBuilder -> ShowS Source # show :: TextBuilder -> String Source # showList :: [TextBuilder] -> ShowS Source #
Eq TextBuilder |
Instance details Defined in TextBuilderCore Methods (==) :: TextBuilder -> TextBuilder -> Bool Source # (/=) :: TextBuilder -> TextBuilder -> Bool Source #

# Accessors

toText :: TextBuilder -> Text Source #

Execute the builder producing a strict text.

toString :: TextBuilder -> String Source #

Convert builder to string.

isEmpty :: TextBuilder -> Bool Source #

Check whether the builder is empty.

# Constructors

## Transformations

force :: TextBuilder -> TextBuilder Source #

Run the builder and pack the produced text into a new builder.

Useful to have around builders that you reuse, because a forced builder is much faster, since it's virtually a single call to `memcopy`.

intercalate :: Foldable f => TextBuilder -> f TextBuilder -> TextBuilder Source #

Intercalate builders.

    >>> intercalate ", " ["a", "b", "c"]
    "a, b, c"

    >>> intercalate ", " ["a"]
    "a"

    >>> intercalate ", " []
    ""

intercalateMap :: Foldable f => TextBuilder -> (a -> TextBuilder) -> f a -> TextBuilder Source #

Intercalate projecting values to builder.

## Textual

text :: Text -> TextBuilder Source #

Strict text.

lazyText :: Text -> TextBuilder Source #

Lazy text.

string :: String -> TextBuilder Source #

Construct from a list of characters.

unsafeUtf8ByteString :: ByteString -> TextBuilder Source #

UTF-8 bytestring. You can use it for converting ASCII values as well.

Warning: It's your responsibility to ensure that the bytestring is properly encoded.

    >>> unsafeUtf8ByteString "abc"
    "abc"

    >>> import Data.Text.Encoding (encodeUtf8)
    >>> unsafeUtf8ByteString (encodeUtf8 "фывапролдж") == "фывапролдж"
    True

## Character

char :: Char -> TextBuilder Source #

Unicode character.

unicodeCodepoint :: Int -> TextBuilder Source #

Safe Unicode codepoint with invalid values replaced by the `�` char (codepoint `0xfffd`), which is the same as what `Data.Text.`pack`` does.

## Integers

### Decimal

decimal :: Integral a => a -> TextBuilder Source #

Signed decimal representation of an integer.

    >>> decimal 123456
    "123456"

    >>> decimal (-123456)
    "-123456"

    >>> decimal 0
    "0"

    >>> decimal (-2 :: Int8)
    "-2"

    >>> decimal (-128 :: Int8)
    "-128"

fixedLengthDecimal :: Integral a => Int -> a -> TextBuilder Source #

Fixed-length decimal without sign. Padded with zeros or trimmed depending on whether it's shorter or longer than specified.

    >>> fixedLengthDecimal 5 123
    "00123"

    >>> fixedLengthDecimal 5 123456
    "23456"

    >>> fixedLengthDecimal 5 (-123456)
    "23456"

    >>> fixedLengthDecimal 7 (-123456)
    "0123456"

    >>> fixedLengthDecimal 0 123
    ""

    >>> fixedLengthDecimal (-2) 123
    ""

thousandSeparatedDecimal :: Integral a => Char -> a -> TextBuilder Source #

Decimal representation of an integral value with thousands separated by the specified character.

    >>> thousandSeparatedDecimal ',' 1234567890
    "1,234,567,890"

    >>> thousandSeparatedDecimal ' ' (-1234567890)
    "-1 234 567 890"

### Binary

binary :: FiniteBits a => a -> TextBuilder Source #

Two's complement binary representation of a value.

Bits of a statically sized value padded from the left according to the size. If it's a negatable integer, the sign is reflected in the bits.

    >>> binary @Int8 0
    "00000000"

    >>> binary @Int8 4
    "00000100"

    >>> binary @Int8 (-1)
    "11111111"

    >>> binary @Word8 255
    "11111111"

    >>> binary @Int16 4
    "0000000000000100"

    >>> binary @Int16 (-4)
    "1111111111111100"

prefixedBinary :: FiniteBits a => a -> TextBuilder Source #

Same as `binary`, but with the "0b" prefix.

    >>> prefixedBinary @Int8 0
    "0b00000000"

### Octal

octal :: (FiniteBits a, Integral a) => a -> TextBuilder Source #

Octal representation of an integer.

    >>> octal @Int32 123456
    "00000361100"

    >>> octal @Int32 (-123456)
    "77777416700"

prefixedOctal :: (FiniteBits a, Integral a) => a -> TextBuilder Source #

Same as `octal`, but with the "0o" prefix.

    >>> prefixedOctal @Int8 0
    "0o000"

### Hexadecimal

hexadecimal :: (FiniteBits a, Integral a) => a -> TextBuilder Source #

Integer in hexadecimal notation with a fixed number of digits determined by the size of the type.

    >>> hexadecimal @Int8 0
    "00"

    >>> hexadecimal @Int8 4
    "04"

    >>> hexadecimal @Int8 (-128)
    "80"

    >>> hexadecimal @Int8 (-1)
    "ff"

    >>> hexadecimal @Word8 255
    "ff"

    >>> hexadecimal @Int32 123456
    "0001e240"

    >>> hexadecimal @Int32 (-123456)
    "fffe1dc0"

prefixedHexadecimal :: (FiniteBits a, Integral a) => a -> TextBuilder Source #

Same as `hexadecimal`, but with the "0x" prefix.

    >>> prefixedHexadecimal @Int8 0
    "0x00"