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


-- | Edge of developments for "text-builder"
--   
--   This is a development version of "<a>text-builder</a>". All
--   experimentation and feature development happens here. The API can
--   change drastically. For a more stable API use "text-builder".
--   
--   The packages are compatible, because they both operate on the type
--   defined in "<a>text-builder-core</a>".
@package text-builder-dev
@version 0.4

module TextBuilderDev

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

-- | Pad a builder from the left side to the specified length with the
--   specified character.
--   
--   <pre>
--   &gt;&gt;&gt; padFromLeft 5 '0' "123"
--   "00123"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; padFromLeft 5 '0' "123456"
--   "123456"
--   </pre>
padFromLeft :: Int -> Char -> TextBuilder -> TextBuilder

-- | Pad a builder from the right side to the specified length with the
--   specified character.
--   
--   <pre>
--   &gt;&gt;&gt; padFromRight 5 ' ' "123"
--   "123  "
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; padFromRight 5 ' ' "123456"
--   "123456"
--   </pre>
padFromRight :: Int -> Char -> TextBuilder -> 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

-- | Hexadecimal readable representation of binary data.
--   
--   <pre>
--   &gt;&gt;&gt; byteStringHexEncoding "Hello"
--   "4865 6c6c 6f"
--   </pre>
byteStringHexEncoding :: ByteString -> 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

-- | Double with a fixed number of decimal places.
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPoint 4 0.123456
--   "0.1235"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPoint 2 2.1
--   "2.10"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPoint (-2) 2.1
--   "2"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPoint 2 (-2.1)
--   "-2.10"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPoint 2 0
--   "0.00"
--   </pre>
doubleFixedPoint :: Int -> Double -> TextBuilder

-- | Double multiplied by 100 with a fixed number of decimal places applied
--   and followed by a percent-sign.
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPointPercent 3 0.123456
--   "12.346%"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPointPercent 0 2
--   "200%"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; doubleFixedPointPercent 0 (-2)
--   "-200%"
--   </pre>
doubleFixedPointPercent :: Int -> Double -> TextBuilder

-- | UTC time in ISO8601 format.
--   
--   <pre>
--   &gt;&gt;&gt; utcTimeIso8601Timestamp (read "2021-11-24 12:11:02 UTC")
--   "2021-11-24T12:11:02Z"
--   </pre>
utcTimeIso8601Timestamp :: UTCTime -> TextBuilder

-- | Time interval in seconds. Directly applicable to <a>DiffTime</a> and
--   <a>NominalDiffTime</a>.
--   
--   The format is the following:
--   
--   <pre>
--   DD:HH:MM:SS
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; realFracDdHhMmSsInterval @Double 59
--   "00:00:00:59"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; realFracDdHhMmSsInterval @Double 90
--   "00:00:01:30"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; realFracDdHhMmSsInterval @Double 86401
--   "01:00:00:01"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; realFracDdHhMmSsInterval @Double (356 * 86400)
--   "356:00:00:00"
--   </pre>
realFracDdHhMmSsInterval :: RealFrac seconds => seconds -> TextBuilder

-- | DiffTime in a compact decimal format based on <a>picoseconds</a>.
diffTimeSeconds :: DiffTime -> TextBuilder

-- | Amount of picoseconds represented in a compact decimal format using
--   suffixes.
--   
--   E.g., the following is <tt>1_230_000_000</tt> picoseconds or 1.23
--   milliseconds or 1230 microseconds:
--   
--   <pre>
--   1230us
--   </pre>
picoseconds :: Integer -> TextBuilder

-- | Data size in decimal notation over amount of bytes.
--   
--   <pre>
--   &gt;&gt;&gt; approximateDataSize 999
--   "999B"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; approximateDataSize 9999
--   "9.9kB"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; approximateDataSize (-9999)
--   "-9.9kB"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; approximateDataSize 1234567890
--   "1.2GB"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; approximateDataSize 10000000000000000000000000000000023
--   "10,000,000,000YB"
--   </pre>
approximateDataSize :: Integral a => a -> TextBuilder

-- | Evidence that there exists an unambiguous way to convert a type to and
--   from <a>TextBuilder</a>.
--   
--   The laws are:
--   
--   <ul>
--   <li><pre><a>from</a> . <a>to</a> = <a>id</a></pre></li>
--   <li><pre><a>to</a> . <a>from</a> = <a>id</a></pre></li>
--   </ul>
--   
--   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).
class Isomorphic a

-- | Project the type into <a>TextBuilder</a>.
from :: Isomorphic a => a -> TextBuilder

-- | Embed <a>TextBuilder</a> into the type.
to :: Isomorphic a => TextBuilder -> a
