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


-- | Efficient and flexible strict text builder
--   
--   <h1>Summary</h1>
--   
--   Fast strict text builder and simple type-safe formatting library.
--   
--   <h2>The Builder</h2>
--   
--   The builder abstraction provided by this library is much faster than
--   the standard lazy <tt>Builder</tt> and even the recently introduced
--   <tt>StrictTextBuilder</tt> 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.
--   
--   <h2>Simple and type-safe formatting library</h2>
--   
--   The monoidal API of the library provides a simple yet type-safe
--   alternative to formatting strings via <tt>printf</tt>-like tools or
--   more involved solutions like the popular "<a>formatting</a>" library.
--   
--   <h2>Quality</h2>
--   
--   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".
--   
--   <h1>Ecosystem</h1>
--   
--   Following is a list of libraries that, alongside this one, make an
--   integrated ecosystem:
--   
--   <ul>
--   <li>"<a>text-builder-time</a>" - formatters for the "time"
--   library</li>
--   <li>"<a>text-builder-core</a>" - lower-level unsafe constructs for
--   implementing efficient formatters compatible with this library</li>
--   <li>"<a>text-builder-dev</a>" - edge of development of new features
--   providing a richer functionality at the cost of more frequent major
--   releases</li>
--   <li>"<a>text-builder-lawful-conversions</a>" - integration with the
--   "lawful-conversions" library, providing bidirectional conversions with
--   various types including <a>String</a>, <a>Data.Text.Text</a>,
--   <a>Data.Text.Lazy.Text</a>, <a>Data.Text.Lazy.Builder.Builder</a>,
--   <a>Data.Text.Encoding.StrictTextBuilder</a>.</li>
--   </ul>
@package text-builder
@version 1.0.0.4

module TextBuilder

-- | Composable specification of how to efficiently construct strict
--   <a>Text</a>.
--   
--   Provides instances of <a>Semigroup</a> and <a>Monoid</a>, which have
--   complexity of <i>O(1)</i>.
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
--   <tt>memcopy</tt>.
force :: TextBuilder -> TextBuilder

-- | Intercalate builders.
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " ["a", "b", "c"]
--   "a, b, c"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " ["a"]
--   "a"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " []
--   ""
--   </pre>
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.
--   
--   <b>Warning:</b> It's your responsibility to ensure that the bytestring
--   is properly encoded.
--   
--   <pre>
--   &gt;&gt;&gt; unsafeUtf8ByteString "abc"
--   "abc"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Text.Encoding (encodeUtf8)
--   
--   &gt;&gt;&gt; unsafeUtf8ByteString (encodeUtf8 "фывапролдж") == "фывапролдж"
--   True
--   </pre>
unsafeUtf8ByteString :: ByteString -> TextBuilder

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

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

-- | Signed decimal representation of an integer.
--   
--   <pre>
--   &gt;&gt;&gt; decimal 123456
--   "123456"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decimal (-123456)
--   "-123456"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decimal 0
--   "0"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decimal (-2 :: Int8)
--   "-2"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decimal (-128 :: Int8)
--   "-128"
--   </pre>
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.
--   
--   <pre>
--   &gt;&gt;&gt; fixedLengthDecimal 5 123
--   "00123"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fixedLengthDecimal 5 123456
--   "23456"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fixedLengthDecimal 5 (-123456)
--   "23456"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fixedLengthDecimal 7 (-123456)
--   "0123456"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fixedLengthDecimal 0 123
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fixedLengthDecimal (-2) 123
--   ""
--   </pre>
fixedLengthDecimal :: Integral a => Int -> a -> TextBuilder

-- | Decimal representation of an integral value with thousands separated
--   by the specified character.
--   
--   <pre>
--   &gt;&gt;&gt; thousandSeparatedDecimal ',' 1234567890
--   "1,234,567,890"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; thousandSeparatedDecimal ' ' (-1234567890)
--   "-1 234 567 890"
--   </pre>
thousandSeparatedDecimal :: Integral a => Char -> a -> TextBuilder

-- | <a>Two's complement</a> 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.
--   
--   <pre>
--   &gt;&gt;&gt; binary @Int8 0
--   "00000000"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; binary @Int8 4
--   "00000100"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; binary @Int8 (-1)
--   "11111111"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; binary @Word8 255
--   "11111111"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; binary @Int16 4
--   "0000000000000100"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; binary @Int16 (-4)
--   "1111111111111100"
--   </pre>
binary :: FiniteBits a => a -> TextBuilder

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

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

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

-- | Integer in hexadecimal notation with a fixed number of digits
--   determined by the size of the type.
--   
--   <pre>
--   &gt;&gt;&gt; hexadecimal @Int8 0
--   "00"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hexadecimal @Int8 4
--   "04"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hexadecimal @Int8 (-128)
--   "80"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hexadecimal @Int8 (-1)
--   "ff"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hexadecimal @Word8 255
--   "ff"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hexadecimal @Int32 123456
--   "0001e240"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hexadecimal @Int32 (-123456)
--   "fffe1dc0"
--   </pre>
hexadecimal :: (FiniteBits a, Integral a) => a -> TextBuilder

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