-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Efficient and flexible strict text builder
--   
--   
Summary
--   
--   Fast strict text builder and simple type-safe formatting library.
--   
--   
The Builder
--   
--   The builder abstraction provided by this library is much faster than
--   the standard lazy Builder and even the recently introduced
--   StrictTextBuilder from "text". Benchmarks are distributed
--   with the source code. You can see the results in the README file.
--   
--   The abstraction constructs text in two phases. In the first one it
--   estimates the size of the byte array and in the second one it
--   allocates it once and populates it in one go.
--   
--   
Simple and type-safe formatting library
--   
--   The monoidal API of the library provides a simple yet type-safe
--   alternative to formatting strings via printf-like tools or
--   more involved solutions like the popular "formatting" library.
--   
--   
Quality
--   
--   Every bit of the library is heavily covered with tests with CI running
--   tests on a variety of versions of GHC and the "text" library. This is
--   crucial because the "text" library has made a switch from UTF-16 to
--   UTF-8, leading to drastic changes in its low-level constructs, which
--   builder libraries must rely on, and this library supports both
--   versions of "text".
--   
--   
Ecosystem
--   
--   Following is a list of libraries that, alongside this one, make an
--   integrated ecosystem:
--   
--   
--   
- "text-builder-time" - formatters for the "time"
--   library
--   
- "text-builder-core" - lower-level unsafe constructs for
--   implementing efficient formatters compatible with this library
--   
- "text-builder-dev" - edge of development of new features
--   providing a richer functionality at the cost of more frequent major
--   releases
--   
- "text-builder-lawful-conversions" - integration with the
--   "lawful-conversions" library, providing bidirectional conversions with
--   various types including String, Data.Text.Text,
--   Data.Text.Lazy.Text, Data.Text.Lazy.Builder.Builder,
--   Data.Text.Encoding.StrictTextBuilder.
--   
@package text-builder
@version 1.0.0.4

module TextBuilder

-- | Composable specification of how to efficiently construct strict
--   Text.
--   
--   Provides instances of Semigroup and Monoid, which have
--   complexity of O(1).
data TextBuilder

-- | Execute the builder producing a strict text.
toText :: TextBuilder -> Text

-- | Convert builder to string.
toString :: TextBuilder -> String

-- | Check whether the builder is empty.
isEmpty :: TextBuilder -> Bool

-- | 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.
force :: TextBuilder -> TextBuilder

-- | Intercalate builders.
--   
--   
--   >>> intercalate ", " ["a", "b", "c"]
--   "a, b, c"
--   
--   
--   
--   >>> intercalate ", " ["a"]
--   "a"
--   
--   
--   
--   >>> intercalate ", " []
--   ""
--   
intercalate :: Foldable f => TextBuilder -> f TextBuilder -> TextBuilder

-- | Intercalate projecting values to builder.
intercalateMap :: Foldable f => TextBuilder -> (a -> TextBuilder) -> f a -> TextBuilder

-- | Strict text.
text :: Text -> TextBuilder

-- | Lazy text.
lazyText :: Text -> TextBuilder

-- | Construct from a list of characters.
string :: String -> TextBuilder

-- | 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
--   
unsafeUtf8ByteString :: ByteString -> TextBuilder

-- | Unicode character.
char :: Char -> TextBuilder

-- | Safe Unicode codepoint with invalid values replaced by the �
--   char (codepoint 0xfffd), which is the same as what
--   Data.Text.pack does.
unicodeCodepoint :: Int -> TextBuilder

-- | Signed decimal representation of an integer.
--   
--   
--   >>> decimal 123456
--   "123456"
--   
--   
--   
--   >>> decimal (-123456)
--   "-123456"
--   
--   
--   
--   >>> decimal 0
--   "0"
--   
--   
--   
--   >>> decimal (-2 :: Int8)
--   "-2"
--   
--   
--   
--   >>> decimal (-128 :: Int8)
--   "-128"
--   
decimal :: Integral a => a -> TextBuilder

-- | 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
--   ""
--   
fixedLengthDecimal :: Integral a => Int -> a -> TextBuilder

-- | 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"
--   
thousandSeparatedDecimal :: Integral a => Char -> a -> TextBuilder

-- | 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"
--   
binary :: FiniteBits a => a -> TextBuilder

-- | Same as binary, but with the "0b" prefix.
--   
--   
--   >>> prefixedBinary @Int8 0
--   "0b00000000"
--   
prefixedBinary :: FiniteBits a => a -> TextBuilder

-- | Octal representation of an integer.
--   
--   
--   >>> octal @Int32 123456
--   "00000361100"
--   
--   
--   
--   >>> octal @Int32 (-123456)
--   "77777416700"
--   
octal :: (FiniteBits a, Integral a) => a -> TextBuilder

-- | Same as octal, but with the "0o" prefix.
--   
--   
--   >>> prefixedOctal @Int8 0
--   "0o000"
--   
prefixedOctal :: (FiniteBits a, Integral a) => a -> TextBuilder

-- | 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"
--   
hexadecimal :: (FiniteBits a, Integral a) => a -> TextBuilder

-- | Same as hexadecimal, but with the "0x" prefix.
--   
--   
--   >>> prefixedHexadecimal @Int8 0
--   "0x00"
--   
prefixedHexadecimal :: (FiniteBits a, Integral a) => a -> TextBuilder
