text-builder-dev-0.4: Edge of developments for "text-builder"

Safe Haskell | None
Language | Haskell2010

TextBuilderDev

Contents

- Accessors
- Constructors
  - Transformations
  - Textual
  - Character
  - Data
  - Integers
    - Decimal
    - Binary
    - Octal
    - Hexadecimal
  - Real
  - Time
  - Other
- Classes

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
- padFromLeft :: Int -> Char -> TextBuilder -> TextBuilder
- padFromRight :: Int -> Char -> TextBuilder -> TextBuilder
- text :: Text -> TextBuilder
- lazyText :: Text -> TextBuilder
- string :: String -> TextBuilder
- unsafeUtf8ByteString :: ByteString -> TextBuilder
- char :: Char -> TextBuilder
- unicodeCodepoint :: Int -> TextBuilder
- byteStringHexEncoding :: ByteString -> 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
- doubleFixedPoint :: Int -> Double -> TextBuilder
- doubleFixedPointPercent :: Int -> Double -> TextBuilder
- utcTimeIso8601Timestamp :: UTCTime -> TextBuilder
- realFracDdHhMmSsInterval :: RealFrac seconds => seconds -> TextBuilder
- diffTimeSeconds :: DiffTime -> TextBuilder
- picoseconds :: Integer -> TextBuilder
- approximateDataSize :: Integral a => a -> TextBuilder
- class Isomorphic a where
  - from :: a -> TextBuilder
  - to :: TextBuilder -> a

# 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 #
Isomorphic TextBuilder Source # |
Instance details Defined in TextBuilderDev.Isomorphic Methods from :: TextBuilder -> TextBuilder Source # to :: TextBuilder -> TextBuilder 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.

padFromLeft :: Int -> Char -> TextBuilder -> TextBuilder Source #

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

    >>> padFromLeft 5 '0' "123"
    "00123"

    >>> padFromLeft 5 '0' "123456"
    "123456"

padFromRight :: Int -> Char -> TextBuilder -> TextBuilder Source #

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

    >>> padFromRight 5 ' ' "123"
    "123  "

    >>> padFromRight 5 ' ' "123456"
    "123456"

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

## Data

byteStringHexEncoding :: ByteString -> TextBuilder Source #

Hexadecimal readable representation of binary data.

    >>> byteStringHexEncoding "Hello"
    "4865 6c6c 6f"

## 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"

## Real

doubleFixedPoint Source #

Arguments

:: Int | Amount of decimals after point.
-> Double |
-> TextBuilder |

Double with a fixed number of decimal places.

    >>> doubleFixedPoint 4 0.123456
    "0.1235"

    >>> doubleFixedPoint 2 2.1
    "2.10"

    >>> doubleFixedPoint (-2) 2.1
    "2"

    >>> doubleFixedPoint 2 (-2.1)
    "-2.10"

    >>> doubleFixedPoint 2 0
    "0.00"

doubleFixedPointPercent Source #

Arguments

:: Int | Amount of decimals after point.
-> Double |
-> TextBuilder |

Double multiplied by 100 with a fixed number of decimal places applied and followed by a percent-sign.

    >>> doubleFixedPointPercent 3 0.123456
    "12.346%"

    >>> doubleFixedPointPercent 0 2
    "200%"

    >>> doubleFixedPointPercent 0 (-2)
    "-200%"

## Time

utcTimeIso8601Timestamp :: UTCTime -> TextBuilder Source #

UTC time in ISO8601 format.

    >>> utcTimeIso8601Timestamp (read "2021-11-24 12:11:02 UTC")
    "2021-11-24T12:11:02Z"

realFracDdHhMmSsInterval :: RealFrac seconds => seconds -> TextBuilder Source #

Time interval in seconds. Directly applicable to `DiffTime` and `NominalDiffTime`.

The format is the following:

    DD:HH:MM:SS

    >>> realFracDdHhMmSsInterval @Double 59
    "00:00:00:59"

    >>> realFracDdHhMmSsInterval @Double 90
    "00:00:01:30"

    >>> realFracDdHhMmSsInterval @Double 86401
    "01:00:00:01"

    >>> realFracDdHhMmSsInterval @Double (356 * 86400)
    "356:00:00:00"

diffTimeSeconds :: DiffTime -> TextBuilder Source #

DiffTime in a compact decimal format based on `picoseconds`.

picoseconds :: Integer -> TextBuilder Source #

Amount of picoseconds represented in a compact decimal format using suffixes.

E.g., the following is `1_230_000_000` picoseconds or 1.23 milliseconds or 1230 microseconds:

    1230us

## Other

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

Data size in decimal notation over amount of bytes.

    >>> approximateDataSize 999
    "999B"

    >>> approximateDataSize 9999
    "9.9kB"

    >>> approximateDataSize (-9999)
    "-9.9kB"

    >>> approximateDataSize 1234567890
    "1.2GB"

    >>> approximateDataSize 10000000000000000000000000000000023
    "10,000,000,000YB"

# Classes

class Isomorphic a where Source #

Evidence that there exists an unambiguous way to convert a type to and from TextBuilder.

The laws are:

-     from . to = id

-     to . from = id

This class does not provide implicit rendering, such as from integer to its decimal representation. There are multiple ways of representing an integer as text (e.g., hexadecimal, binary). The non-ambiguity is further enforced by the presence of the inverse conversion. In the integer case there is no way to read it from a textual form without a possibility of failing (e.g., when the input string cannot be parsed as an integer).

Methods

from :: a -> TextBuilder Source #

Project the type into TextBuilder.

to :: TextBuilder -> a Source #

Embed TextBuilder into the type.

#### Instances

Instances details

Isomorphic Text Source # |
Instance details Defined in TextBuilderDev.Isomorphic Methods from :: Text -> TextBuilder Source # to :: TextBuilder -> Text Source #
Isomorphic Builder Source # |
Instance details Defined in TextBuilderDev.Isomorphic Methods from :: Builder -> TextBuilder Source # to :: TextBuilder -> Builder Source #
Isomorphic Text Source # |
Instance details Defined in TextBuilderDev.Isomorphic Methods from :: Text -> TextBuilder Source # to :: TextBuilder -> Text Source #
Isomorphic StrictTextBuilder Source # |
Instance details Defined in TextBuilderDev.Domains.StrictTextBuilder Methods from :: StrictTextBuilder -> TextBuilder Source # to :: TextBuilder -> StrictTextBuilder Source #
Isomorphic TextBuilder Source # |
Instance details Defined in TextBuilderDev.Isomorphic Methods from :: TextBuilder -> TextBuilder Source # to :: TextBuilder -> TextBuilder Source #