A class similar to Show, serving the purpose that quickly convert a data type to a Text value.

You can use newtype or generic deriving to implement instance of this class quickly:

 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
 {-# LANGUAGE DeriveAnyClass #-}
 {-# LANGUAGE DeriveGeneric #-}
 {-# LANGUAGE DerivingStrategies #-}

 import GHC.Generics

 newtype FooInt = FooInt Int deriving (Generic)
                           deriving anyclass ShowT

> toText (FooInt 3)
> "FooInt 3"

 newtype FooInt = FooInt Int deriving (Generic)
                           deriving newtype ShowT

> toText (FooInt 3)
> "3"

Convert data to Text.

Convert data to String, faster show replacement.

Convert data to Builder.

Convert data to Bytes in UTF8 encoding.

Escape text using JSON string escaping rules and add double quotes, escaping rules:

   '\b':  "\b"
   '\f':  "\f"
   '\n':  "\n"
   '\r':  "\r"
   '\t':  "\t"
   '"':  "\""
   '\':  "\\"
   '/':  "\/"
   other chars <= 0x1F: "\u00XX"

Turn String into Builder with UTF8 encoding

Illegal codepoints will be written as replacementChars.

This is different from writing string literals builders via OverloadedStrings, because string literals do not provide UTF8 guarantees.

This function will be rewritten into a memcpy if possible, (running a fast UTF-8 validation at runtime first).

Turn Char into Builder with UTF8 encoding

Illegal codepoints will be written as replacementChars.

Turn String into Builder with ASCII7 encoding

Codepoints beyond 'x7F' will be chopped.

Turn Char into Builder with ASCII7 encoding

Codepoints beyond 'x7F' will be chopped.

Write UTF8 encoded Text using Builder.

Note, if you're trying to write string literals builders, please open OverloadedStrings and use Builders IsString instance, it will be rewritten into a memcpy.

Integral formatting options.

defaultIFormat = IFormat 0 NoPadding False

int = intWith defaultIFormat

Format a Bounded Integral type like Int or Word16 into decimal ASCII digits.

import Z.Data.Builder as B
import Z.Data.Text    as T

> T.validate . B.buildBytes $ B.intWith defaultIFormat  (12345 :: Int)
"12345"
> T.validate . B.buildBytes $ B.intWith defaultIFormat{width=10, padding=RightSpacePadding} (12345 :: Int)
"12345     "
> T.validate . B.buildBytes $ B.intWith defaultIFormat{width=10, padding=ZeroPadding} (12345 :: Int)
"0000012345"

Format a Integer into decimal ASCII digits.

Format a FiniteBits Integral type into hex nibbles.

import Z.Data.Builder as B
import Z.Data.Text    as T
import Data.Word
import Data.Int

> T.validate . B.buildBytes $ B.hex (125 :: Int8)
"7d"
> T.validate . B.buildBytes $ B.hex (-1 :: Int8)
"ff"
> T.validate . B.buildBytes $ B.hex (125 :: Word16)
"007d"

The UPPERCASED version of hex.

Control the rendering of floating point numbers.

Decimal encoding of an IEEE Double.

Using standard decimal notation for arguments whose absolute value lies between 0.1 and 9,999,999, and scientific notation otherwise.

Format double-precision float using drisu3 with dragon4 fallback.

Decimal encoding of an IEEE Float.

Using standard decimal notation for arguments whose absolute value lies between 0.1 and 9,999,999, and scientific notation otherwise.

Format single-precision float using drisu3 with dragon4 fallback.

A Builder which renders a scientific number to full precision, using standard decimal notation for arguments whose absolute value lies between 0.1 and 9,999,999, and scientific notation otherwise.

Like scientific but provides rendering options.

add (...) to original builder.

add {...} to original builder.

add [...] to original builder.

add <...> to original builder.

add "..." to original builder.

add '...' to original builder.

write an ASCII :

write an ASCII ,

Use separator to connect a vector of builders.

import Z.Data.Builder as B
import Z.Data.Text    as T
import Z.Data.Vector  as V

> T.validate . B.build $ B.intercalateVec "," B.int (V.pack [1,2,3,4] :: V.PrimVector Int)
"1,2,3,4"

Use separator to connect list of builders.

import Z.Data.Builder as B
import Z.Data.Text    as T
import Z.Data.Vector  as V

T.validate . B.build $ B.intercalateList "," B.int ([1,2,3,4] :: [Int])
"1,2,3,4"

Add "(..)" around builders when condition is met, otherwise add nothing.

This is useful when defining ShowT instances.