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


-- | Build byte arrays
--   
--   This is similar to the builder facilities provided by
--   <a>Data.ByteString.Builder</a>. It is intended to be used in
--   situations where the following apply:
--   
--   <ul>
--   <li>An individual entity will be serialized as a small number of bytes
--   (less than 512).</li>
--   <li>A large number (more than 32) of entities will be serialized one
--   after another without anything between them.</li>
--   </ul>
--   
--   Unlike builders from the <a>bytestring</a> package, these builders do
--   not track their state when they run out of space. A builder that runs
--   out of space simply aborts and is rerun at the beginning of the next
--   chunk. This strategy for building is suitable for most CSVs and
--   several line protocols (carbon, InfluxDB, etc.).
@package bytebuild
@version 0.3.16.3

module Data.Bytes.Builder.Bounded.Unsafe

-- | A builder parameterized by the maximum number of bytes it uses when
--   executed.
newtype Builder :: Nat -> Type
[Builder] :: (forall s. MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)) -> Builder n

-- | Constructor for <a>Builder</a> that works on a function with lifted
--   arguments instead of unlifted ones. This is just as unsafe as the
--   actual constructor.
construct :: (forall s. MutableByteArray s -> Int -> ST s Int) -> Builder n

-- | This function does not enforce the known upper bound on the size. It
--   is up to the user to do this.
pasteST :: Builder n -> MutableByteArray s -> Int -> ST s Int

-- | This function does not enforce the known upper bound on the size. It
--   is up to the user to do this.
pasteIO :: Builder n -> MutableByteArray RealWorld -> Int -> IO Int


-- | The functions in this module are explict about the maximum number of
--   bytes they require.
module Data.Bytes.Builder.Bounded

-- | A builder parameterized by the maximum number of bytes it uses when
--   executed.
data Builder :: Nat -> Type

-- | Execute the bounded builder. If the size is a constant, use
--   <tt>Arithmetic.Nat.constant</tt> as the first argument to let GHC
--   conjure up this value for you.
run :: Nat n -> Builder n -> ByteArray

-- | Variant of <a>run</a> that puts the result in a pinned buffer and
--   packs it up in a <a>ByteString</a>.
runByteString :: Nat n -> Builder n -> ByteString

-- | Paste the builder into the byte array starting at offset zero. This
--   reallocates the byte array if it cannot accomodate the builder,
--   growing it by the minimum amount necessary.
pasteGrowST :: Nat n -> Builder n -> MutableByteArrayOffset s -> ST s (MutableByteArrayOffset s)

-- | The monoidal unit of <a>append</a>
empty :: Builder 0

-- | Concatenate two builders.
append :: Builder m -> Builder n -> Builder (m + n)
infixr 9 `append`

-- | Weaken the bound on the maximum number of bytes required. For example,
--   to use two builders with unequal bounds in a disjunctive setting:
--   
--   <pre>
--   import qualified Arithmetic.Lte as Lte
--   
--   buildNumber :: Either Double Word64 -&gt; Builder 32
--   buildNumber = \case
--     Left d  -&gt; doubleDec d
--     Right w -&gt; weaken (Lte.constant @19 @32) (word64Dec w)
--   </pre>
weaken :: forall m n. (m <= n) -> Builder m -> Builder n

-- | Replace the upper bound on size with an equal number.
substitute :: forall m n. (m :=: n) -> Builder m -> Builder n

-- | Requires up to 19 bytes. Encodes an unsigned 64-bit integer as
--   decimal. This encoding never starts with a zero unless the argument
--   was zero.
word64Dec :: Word64 -> Builder 19

-- | Requires up to 10 bytes. Encodes an unsigned 32-bit integer as
--   decimal. This encoding never starts with a zero unless the argument
--   was zero.
word32Dec :: Word32 -> Builder 10

-- | Requires up to 5 bytes. Encodes an unsigned 16-bit integer as decimal.
--   This encoding never starts with a zero unless the argument was zero.
word16Dec :: Word16 -> Builder 5

-- | Requires up to 3 bytes. Encodes an unsigned 8-bit integer as decimal.
--   This encoding never starts with a zero unless the argument was zero.
word8Dec :: Word8 -> Builder 3

-- | Requires up to 19 bytes. Encodes an unsigned machine-sized integer as
--   decimal. This encoding never starts with a zero unless the argument
--   was zero.
wordDec :: Word -> Builder 19

-- | Requires up to 20 bytes. Encodes a signed 64-bit integer as decimal.
--   This encoding never starts with a zero unless the argument was zero.
--   Negative numbers are preceded by a minus sign. Positive numbers are
--   not preceded by anything.
int64Dec :: Int64 -> Builder 20

-- | Requires up to 11 bytes. Encodes a signed 32-bit integer as decimal.
--   This encoding never starts with a zero unless the argument was zero.
--   Negative numbers are preceded by a minus sign. Positive numbers are
--   not preceded by anything.
int32Dec :: Int32 -> Builder 11

-- | Requires up to 6 bytes. Encodes a signed 16-bit integer as decimal.
--   This encoding never starts with a zero unless the argument was zero.
--   Negative numbers are preceded by a minus sign. Positive numbers are
--   not preceded by anything.
int16Dec :: Int16 -> Builder 6

-- | Requires up to 4 bytes. Encodes a signed 8-bit integer as decimal.
--   This encoding never starts with a zero unless the argument was zero.
--   Negative numbers are preceded by a minus sign. Positive numbers are
--   not preceded by anything.
int8Dec :: Int8 -> Builder 4

-- | Requires up to 20 bytes. Encodes a signed machine-sized integer as
--   decimal. This encoding never starts with a zero unless the argument
--   was zero. Negative numbers are preceded by a minus sign. Positive
--   numbers are not preceded by anything.
intDec :: Int -> Builder 20

-- | Requires exactly 32 bytes. Encodes a 128-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 32 digits. This uses
--   lowercase for the alphabetical digits.
word128PaddedLowerHex :: Word128 -> Builder 32

-- | Requires exactly 32 bytes. Encodes a 128-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 32 digits. This uses
--   uppercase for the alphabetical digits.
word128PaddedUpperHex :: Word128 -> Builder 32

-- | Requires exactly 64 bytes. Encodes a 256-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 64 digits. This uses
--   lowercase for the alphabetical digits.
word256PaddedLowerHex :: Word256 -> Builder 64

-- | Requires exactly 64 bytes. Encodes a 256-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 64 digits. This uses
--   uppercase for the alphabetical digits.
word256PaddedUpperHex :: Word256 -> Builder 64

-- | Requires exactly 16 bytes. Encodes a 64-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 16 digits. This uses
--   lowercase for the alphabetical digits. For example, this encodes the
--   number 1022 as <tt>00000000000003fe</tt>.
word64PaddedLowerHex :: Word64 -> Builder 16

-- | Requires exactly 16 bytes. Encodes a 64-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 16 digits. This uses
--   uppercase for the alphabetical digits. For example, this encodes the
--   number 1022 as <tt>00000000000003FE</tt>.
word64PaddedUpperHex :: Word64 -> Builder 16

-- | Requires exactly 12 bytes. Discards the upper 16 bits of a 64-bit
--   unsigned integer and then encodes the lower 48 bits as hexadecimal,
--   zero-padding the encoding to 12 digits. This uses lowercase for the
--   alphabetical digits. For example, this encodes the number 1022 as
--   <tt>0000000003fe</tt>.
word48PaddedLowerHex :: Word64 -> Builder 12

-- | Requires exactly 8 bytes. Encodes a 32-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 8 digits. This uses
--   lowercase for the alphabetical digits.
word32PaddedLowerHex :: Word32 -> Builder 8

-- | Requires exactly 8 bytes. Encodes a 32-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 8 digits. This uses
--   uppercase for the alphabetical digits.
word32PaddedUpperHex :: Word32 -> Builder 8

-- | Requires exactly 4 bytes. Encodes a 16-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 4 digits. This uses
--   lowercase for the alphabetical digits.
--   
--   <pre>
--   &gt;&gt;&gt; word16PaddedLowerHex 0xab0
--   0ab0
--   </pre>
word16PaddedLowerHex :: Word16 -> Builder 4

-- | Requires exactly 4 bytes. Encodes a 16-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 4 digits. This uses
--   uppercase for the alphabetical digits.
--   
--   <pre>
--   &gt;&gt;&gt; word16PaddedUpperHex 0xab0
--   0AB0
--   </pre>
word16PaddedUpperHex :: Word16 -> Builder 4

-- | Requires at most 4 bytes. Encodes a 16-bit unsigned integer as
--   hexadecimal. No leading zeroes are displayed. Letters are presented in
--   lowercase. If the number is zero, a single zero digit is used.
--   
--   <pre>
--   &gt;&gt;&gt; word16LowerHex 0xab0
--   ab0
--   </pre>
word16LowerHex :: Word16 -> Builder 4

-- | Requires at most 4 bytes. Encodes a 16-bit unsigned integer as
--   hexadecimal. No leading zeroes are displayed. Letters are presented in
--   uppercase. If the number is zero, a single zero digit is used.
--   
--   <pre>
--   &gt;&gt;&gt; word16UpperHex 0xab0
--   AB0
--   </pre>
word16UpperHex :: Word16 -> Builder 4

-- | Requires exactly 2 bytes. Encodes a 8-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 2 digits. This uses
--   lowercase for the alphabetical digits.
word8PaddedLowerHex :: Word8 -> Builder 2

-- | Requires exactly 2 bytes. Encodes a 8-bit unsigned integer as
--   hexadecimal, zero-padding the encoding to 2 digits. This uses
--   uppercase for the alphabetical digits.
word8PaddedUpperHex :: Word8 -> Builder 2

-- | Requires at most 2 bytes. Encodes a 8-bit unsigned integer as
--   hexadecimal. No leading zeroes are displayed. If the number is zero, a
--   single zero digit is used.
word8LowerHex :: Word8 -> Builder 2

-- | Encode an ASCII character. Precondition: Input must be an ASCII
--   character. This is not checked.
ascii :: Char -> Builder 1

-- | Encode two ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii2 :: Char -> Char -> Builder 2

-- | Encode three ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii3 :: Char -> Char -> Char -> Builder 3

-- | Encode four ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii4 :: Char -> Char -> Char -> Char -> Builder 4

-- | Encode five ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii5 :: Char -> Char -> Char -> Char -> Char -> Builder 5

-- | Encode six ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii6 :: Char -> Char -> Char -> Char -> Char -> Char -> Builder 6

-- | Encode seven ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii7 :: Char -> Char -> Char -> Char -> Char -> Char -> Char -> Builder 7

-- | Encode eight ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii8 :: Char -> Char -> Char -> Char -> Char -> Char -> Char -> Char -> Builder 8

-- | Encode a character as UTF-8. This only uses as much space as is
--   required.
char :: Char -> Builder 4

-- | Encode a number less than 100 as a decimal number, zero-padding it to
--   two digits. For example: 0 is encoded as <tt>00</tt>, 5 is encoded as
--   <tt>05</tt>, and 73 is encoded as <tt>73</tt>.
--   
--   Precondition: Argument must be less than 100. Failure to satisfy this
--   precondition will not result in a segfault, but the resulting bytes
--   are undefined. The implemention uses a heuristic for division that is
--   inaccurate for large numbers.
wordPaddedDec2 :: Word -> Builder 2
wordPaddedDec3 :: Word -> Builder 3

-- | Encode a number less than 10000 as a decimal number, zero-padding it
--   to two digits. For example: 0 is encoded as <tt>0000</tt>, 5 is
--   encoded as <tt>0005</tt>, and 73 is encoded as <tt>0073</tt>.
--   
--   Precondition: Argument must be less than 10000. Failure to satisfy
--   this precondition will not result in a segfault, but the resulting
--   bytes are undefined. The implemention uses a heuristic for division
--   that is inaccurate for large numbers.
wordPaddedDec4 :: Word -> Builder 4

-- | Encode a number less than 1e9 as a decimal number, zero-padding it to
--   nine digits. For example: 0 is encoded as <tt>000000000</tt> and 5 is
--   encoded as <tt>000000005</tt>.
--   
--   Precondition: Argument must be less than 1e9. Failure to satisfy this
--   precondition will not result in a segfault, but the resulting bytes
--   are undefined. The implemention uses a heuristic for division that is
--   inaccurate for large numbers.
wordPaddedDec9 :: Word -> Builder 9
word8 :: Word8 -> Builder 1
word256BE :: Word256 -> Builder 32
word128BE :: Word128 -> Builder 16

-- | Requires exactly 8 bytes. Dump the octets of a 64-bit word in a
--   big-endian fashion.
word64BE :: Word64 -> Builder 8

-- | Requires exactly 4 bytes. Dump the octets of a 32-bit word in a
--   big-endian fashion.
word32BE :: Word32 -> Builder 4

-- | Requires exactly 2 bytes. Dump the octets of a 16-bit word in a
--   big-endian fashion.
word16BE :: Word16 -> Builder 2
int64BE :: Int64 -> Builder 8
int32BE :: Int32 -> Builder 4
int16BE :: Int16 -> Builder 2
word256LE :: Word256 -> Builder 32
word128LE :: Word128 -> Builder 16

-- | Requires exactly 8 bytes. Dump the octets of a 64-bit word in a
--   little-endian fashion.
word64LE :: Word64 -> Builder 8

-- | Requires exactly 4 bytes. Dump the octets of a 32-bit word in a
--   little-endian fashion.
word32LE :: Word32 -> Builder 4

-- | Requires exactly 2 bytes. Dump the octets of a 16-bit word in a
--   little-endian fashion.
word16LE :: Word16 -> Builder 2
int64LE :: Int64 -> Builder 8
int32LE :: Int32 -> Builder 4
int16LE :: Int16 -> Builder 2

-- | Encode a machine-sized word with LEB-128.
wordLEB128 :: Word -> Builder 10

-- | Encode a 32-bit word with LEB-128.
word16LEB128 :: Word16 -> Builder 3

-- | Encode a 32-bit word with LEB-128.
word32LEB128 :: Word32 -> Builder 5

-- | Encode a 64-bit word with LEB-128.
word64LEB128 :: Word64 -> Builder 10

-- | Encode a machine-sized word with VLQ (also known as VByte, Varint,
--   VInt).
wordVlq :: Word -> Builder 10

-- | Encode a 32-bit word with VLQ (also known as VByte, Varint, VInt).
word32Vlq :: Word32 -> Builder 5

-- | Encode a 64-bit word with VLQ (also known as VByte, Varint, VInt).
word64Vlq :: Word64 -> Builder 10

-- | Encode a double-floating-point number, using decimal notation or
--   scientific notation depending on the magnitude. This has undefined
--   behavior when representing <tt>+inf</tt>, <tt>-inf</tt>, and
--   <tt>NaN</tt>. It will not crash, but the generated numbers will be
--   nonsense.
doubleDec :: Double -> Builder 32

module Data.Bytes.Builder.Bounded.Class

-- | Variant of To that can be encoded as a builder. Human-readable
--   encodings are used when possible. For example, numbers are encoded an
--   ascii-encoded decimal characters. UTF-8 is preferred for textual
--   types. For types that represent arbitrary bytes (e.g. Bytes,
--   ByteString), the bytes are preserved.
--   
--   The goal of this typeclass is to reduce the size of builders produced
--   by quasiquotation.
class ToBoundedBuilder a where {
    type BoundedBuilderLength a :: Nat;
}
toBuilder :: ToBoundedBuilder a => a -> Builder (BoundedBuilderLength a)
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder (Data.Bytes.Builder.Bounded.Unsafe.Builder n)
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Int.Int64
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Int.Int32
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Int.Int16
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Int.Int8
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Types.Int
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Word.Word64
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Word.Word32
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Word.Word16
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Word.Word8
instance Data.Bytes.Builder.Bounded.Class.ToBoundedBuilder GHC.Types.Word

module Data.Bytes.Builder.Unsafe

-- | An unmaterialized sequence of bytes that may be pasted into a mutable
--   byte array.
newtype Builder
Builder :: (forall s. MutableByteArray# s -> Int# -> Int# -> Commits s -> State# s -> (# State# s, MutableByteArray# s, Int#, Int#, Commits s #)) -> Builder

-- | A list of committed chunks along with the chunk currently being
--   written to. This is kind of like a non-empty variant of
--   <tt>Commmits</tt> but with the additional invariant that the head
--   chunk is a mutable byte array.
data BuilderState s
BuilderState :: MutableByteArray# s -> Int# -> Int# -> !Commits s -> BuilderState s
data Commits s
Mutable :: MutableByteArray# s -> Int# -> !Commits s -> Commits s
Immutable :: ByteArray# -> Int# -> Int# -> !Commits s -> Commits s
Initial :: Commits s

-- | Run a builder, performing an in-place update on the state. The
--   <tt>BuilderState</tt> argument must not be reused after being passed
--   to this function. That is, its use must be affine.
pasteST :: Builder -> BuilderState s -> ST s (BuilderState s)

-- | Variant of <a>pasteST</a> that runs in <a>IO</a>.
pasteIO :: Builder -> BuilderState RealWorld -> IO (BuilderState RealWorld)
fromEffect :: Int -> (forall s. MutableByteArray s -> Int -> ST s Int) -> Builder

-- | Create an empty <a>BuilderState</a> with a buffer of the given size.
newBuilderState :: Int -> ST s (BuilderState s)

-- | Push the active chunk onto the top of the commits. The
--   <tt>BuilderState</tt> argument must not be reused after being passed
--   to this function. That is, its use must be affine.
closeBuilderState :: BuilderState s -> Commits s

-- | Cons the chunks from a list of <tt>Commits</tt> onto an initial
--   <tt>Chunks</tt> list (this argument is often <tt>ChunksNil</tt>). This
--   reverses the order of the chunks, which is desirable since builders
--   assemble <tt>Commits</tt> with the chunks backwards. This performs an
--   in-place shrink and freezes any mutable byte arrays it encounters.
--   Consequently, these must not be reused.
reverseCommitsOntoChunks :: Chunks -> Commits s -> ST s Chunks

-- | Variant of <a>reverseCommitsOntoChunks</a> that does not reverse the
--   order of the commits. Since commits are built backwards by consing,
--   this means that the chunks appended to the front will be backwards.
--   Within each chunk, however, the bytes will be in the correct order.
--   
--   Unlike <a>reverseCommitsOntoChunks</a>, this function is not tail
--   recursive.
commitsOntoChunks :: Chunks -> Commits s -> ST s Chunks

-- | Copy the contents of the chunks into a mutable array, reversing the
--   order of the chunks. Precondition: The destination must have enough
--   space to house the contents. This is not checked.
copyReverseCommits :: MutableByteArray s -> Int -> Commits s -> ST s Int

-- | Add the total number of bytes in the commits to first argument.
addCommitsLength :: Int -> Commits s -> Int

-- | Compute the number of bytes between the last byte and the offset
--   specified in a chunk. Precondition: the chunk must exist in the list
--   of committed chunks. This relies on mutable byte arrays having
--   identity (e.g. it uses <tt>sameMutableByteArray#</tt>).
commitDistance :: MutableByteArray# s -> Int# -> Commits s -> Int#

-- | Variant of commitDistance where you get to supply a head of the commit
--   list that has not yet been committed.
commitDistance1 :: MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Commits s -> Int#

-- | Create a builder from a cons-list of <a>Char</a>. These must be UTF-8
--   encoded.
stringUtf8 :: String -> Builder

-- | Create a builder from a <tt>NUL</tt>-terminated <a>CString</a>. This
--   ignores any textual encoding, copying bytes until <tt>NUL</tt> is
--   reached.
cstring :: CString -> Builder

-- | Encode (UTF-8 encoded) text as a JSON string, wrapping it in double
--   quotes. This escapes all characters with code points below
--   <tt>0x20</tt>.
--   
--   <ul>
--   <li>Precondition: The slice of the byte argument is UTF-8 encoded
--   text.</li>
--   <li>Precondition: There is enough space in the buffer for the result
--   to be written to. A simple way to ensure enough space is to allocate
--   <tt>6N + 2</tt> bytes, where N is the length of the argument. However,
--   the caller may use clever heuristics to find a lower upper bound.</li>
--   <li>Result: The next offset in the destination buffer</li>
--   </ul>
pasteUtf8TextJson# :: ByteArray# -> Int# -> Int# -> MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
instance Data.String.IsString Data.Bytes.Builder.Unsafe.Builder
instance GHC.Base.Semigroup Data.Bytes.Builder.Unsafe.Builder
instance GHC.Base.Monoid Data.Bytes.Builder.Unsafe.Builder

module Data.Bytes.Builder

-- | An unmaterialized sequence of bytes that may be pasted into a mutable
--   byte array.
data Builder

-- | Convert a bounded builder to an unbounded one. If the size is a
--   constant, use <tt>Arithmetic.Nat.constant</tt> as the first argument
--   to let GHC conjure up this value for you.
fromBounded :: Nat n -> Builder n -> Builder

-- | Run a builder.
run :: Int -> Builder -> Chunks

-- | Run a builder. The resulting chunks are consed onto the beginning of
--   an existing sequence of chunks.
runOnto :: Int -> Builder -> Chunks -> Chunks

-- | Variant of <a>runOnto</a> that additionally returns the number of
--   bytes consed onto the suffix.
runOntoLength :: Int -> Builder -> Chunks -> (Int, Chunks)

-- | Variant of <a>runOnto</a> that conses the additional chunks in reverse
--   order.
reversedOnto :: Int -> Builder -> Chunks -> Chunks

-- | Run a builder against lots of elements. This fills the same underlying
--   buffer over and over again. Do not let the argument to the callback
--   escape from the callback (i.e. do not write it to an <tt>IORef</tt>).
--   Also, do not <tt>unsafeFreezeByteArray</tt> any of the mutable byte
--   arrays in the callback. The intent is that the callback will write the
--   buffer out.
putMany :: Foldable f => Int -> (a -> Builder) -> f a -> (MutableBytes RealWorld -> IO b) -> IO ()

-- | Variant of <a>putMany</a> that prefixes each pushed array of chunks
--   with the number of bytes that the chunks in each batch required. (This
--   excludes the bytes required to encode the length itself.) This is
--   useful for chunked HTTP encoding.
putManyConsLength :: (Foldable f, MonadIO m) => Nat n -> (Int -> Builder n) -> Int -> (a -> Builder) -> f a -> (MutableBytes RealWorld -> m b) -> m ()

-- | Create a builder from a sliced byte sequence. The variants <a>copy</a>
--   and <a>insert</a> provide more control over whether or not the byte
--   sequence is copied or aliased. This function is preferred when the
--   user does not know the size of the byte sequence.
bytes :: Bytes -> Builder

-- | Paste byte chunks into a builder.
chunks :: Chunks -> Builder

-- | Create a builder from a byte sequence. This always results in a call
--   to <tt>memcpy</tt>. This is beneficial when the byte sequence is known
--   to be small (less than 256 bytes).
copy :: Bytes -> Builder

-- | Variant of <a>copy</a> that additionally pastes an extra byte in front
--   of the bytes.
copyCons :: Word8 -> Bytes -> Builder

-- | Create a builder from two byte sequences. This always results in two
--   calls to <tt>memcpy</tt>. This is beneficial when the byte sequences
--   are known to be small (less than 256 bytes).
copy2 :: Bytes -> Bytes -> Builder

-- | Create a builder from a byte sequence. This never calls
--   <tt>memcpy</tt>. Instead, it pushes a chunk that references the
--   argument byte sequence. This wastes the remaining space in the active
--   chunk, so it may adversely affect performance if used carelessly. See
--   <a>flush</a> for a way to mitigate this problem. This functions is
--   most beneficial when the byte sequence is known to be large (more than
--   8192 bytes).
insert :: Bytes -> Builder

-- | Create a builder from an unsliced byte sequence. Implemented with
--   <a>bytes</a>.
byteArray :: ByteArray -> Builder

-- | Create a builder from a short bytestring. Implemented with
--   <a>bytes</a>.
shortByteString :: ShortByteString -> Builder

-- | Create a builder from text. The text will be UTF-8 encoded.
textUtf8 :: Text -> Builder
textJsonString :: Text -> Builder

-- | Create a builder from text. The text will be UTF-8 encoded.
shortTextUtf8 :: ShortText -> Builder

-- | Create a builder from text. The text will be UTF-8 encoded, and JSON
--   special characters will be escaped. Additionally, the result is
--   surrounded by double quotes. For example:
--   
--   <ul>
--   <li><tt>foo ==&gt; "foo"</tt> (no escape sequences)</li>
--   <li><tt>\_"_/ ==&gt; "\\_\"_/"</tt> (escapes backslashes and
--   quotes)</li>
--   <li><tt>hello&lt;ESC&gt;world ==&gt; "hello\u001Bworld"</tt> (where
--   <tt>&lt;ESC&gt;</tt> is code point 0x1B)</li>
--   </ul>
shortTextJsonString :: ShortText -> Builder

-- | Create a builder from a <tt>NUL</tt>-terminated <a>CString</a>. This
--   ignores any textual encoding, copying bytes until <tt>NUL</tt> is
--   reached.
cstring :: CString -> Builder
cstring# :: Addr# -> Builder

-- | Create a builder from a C string with explicit length. The builder
--   must be executed before the C string is freed.
cstringLen :: CStringLen -> Builder

-- | Create a builder from a cons-list of <a>Char</a>. These must be UTF-8
--   encoded.
stringUtf8 :: String -> Builder

-- | Encode seven bytes into eight so that the encoded form is eight-bit
--   clean. Specifically segment the input bytes inot 7-bit groups
--   (lowest-to-highest index byte, most-to-least significant bit within a
--   byte), pads the last group with trailing zeros, and forms octects by
--   prepending a zero to each group.
--   
--   The name was chosen because this pads the input bits with zeros on the
--   right, and also because this was likely the originally-indended
--   behavior of the SMILE standard (see <a>sevenEightSmile</a>). Right
--   padding the input bits to a multiple of seven, as in this variant, is
--   consistent with base64 encodings (which encodes 3 bytes in 4) and
--   base85 (which encodes 4 bytes in 5).
sevenEightRight :: Bytes -> Builder

-- | Encode seven bytes into eight so that the encoded form is eight-bit
--   clean. Specifically segment the input bytes inot 7-bit groups
--   (lowest-to-highest index byte, most-to-least significant bit within a
--   byte), then pad each group with zeros on the left until each group is
--   an octet.
--   
--   The name was chosen because this is the implementation that is used
--   (probably unintentionally) in the reference SMILE implementation, and
--   so is expected tp be accepted by existing SMILE consumers.
sevenEightSmile :: Bytes -> Builder

-- | Encodes an unsigned 64-bit integer as decimal. This encoding never
--   starts with a zero unless the argument was zero.
word64Dec :: Word64 -> Builder

-- | Encodes an unsigned 16-bit integer as decimal. This encoding never
--   starts with a zero unless the argument was zero.
word32Dec :: Word32 -> Builder

-- | Encodes an unsigned 16-bit integer as decimal. This encoding never
--   starts with a zero unless the argument was zero.
word16Dec :: Word16 -> Builder

-- | Encodes an unsigned 8-bit integer as decimal. This encoding never
--   starts with a zero unless the argument was zero.
word8Dec :: Word8 -> Builder

-- | Encodes an unsigned machine-sized integer as decimal. This encoding
--   never starts with a zero unless the argument was zero.
wordDec :: Word -> Builder

-- | Encodes an unsigned arbitrary-precision integer as decimal. This
--   encoding never starts with a zero unless the argument was zero.
naturalDec :: Natural -> Builder

-- | Encodes a signed 64-bit integer as decimal. This encoding never starts
--   with a zero unless the argument was zero. Negative numbers are
--   preceded by a minus sign. Positive numbers are not preceded by
--   anything.
int64Dec :: Int64 -> Builder

-- | Encodes a signed 32-bit integer as decimal. This encoding never starts
--   with a zero unless the argument was zero. Negative numbers are
--   preceded by a minus sign. Positive numbers are not preceded by
--   anything.
int32Dec :: Int32 -> Builder

-- | Encodes a signed 16-bit integer as decimal. This encoding never starts
--   with a zero unless the argument was zero. Negative numbers are
--   preceded by a minus sign. Positive numbers are not preceded by
--   anything.
int16Dec :: Int16 -> Builder

-- | Encodes a signed 8-bit integer as decimal. This encoding never starts
--   with a zero unless the argument was zero. Negative numbers are
--   preceded by a minus sign. Positive numbers are not preceded by
--   anything.
int8Dec :: Int8 -> Builder

-- | Encodes a signed machine-sized integer as decimal. This encoding never
--   starts with a zero unless the argument was zero. Negative numbers are
--   preceded by a minus sign. Positive numbers are not preceded by
--   anything.
intDec :: Int -> Builder

-- | Encode a signed arbitrary-precision integer as decimal. This encoding
--   never starts with a zero unless the argument was zero. Negative
--   numbers are preceded by a minus sign. Positive numbers are not
--   preceded by anything.
integerDec :: Integer -> Builder

-- | Encode a 64-bit unsigned integer as hexadecimal, zero-padding the
--   encoding to 16 digits. This uses uppercase for the alphabetical
--   digits. For example, this encodes the number 1022 as
--   <tt>00000000000003FE</tt>.
word64PaddedUpperHex :: Word64 -> Builder

-- | Encode a 32-bit unsigned integer as hexadecimal, zero-padding the
--   encoding to 8 digits. This uses uppercase for the alphabetical digits.
--   For example, this encodes the number 1022 as <tt>000003FE</tt>.
word32PaddedUpperHex :: Word32 -> Builder

-- | Encode a 16-bit unsigned integer as hexadecimal, zero-padding the
--   encoding to 4 digits. This uses uppercase for the alphabetical digits.
--   For example, this encodes the number 1022 as <tt>03FE</tt>.
word16PaddedUpperHex :: Word16 -> Builder

-- | Encode a 16-bit unsigned integer as hexadecimal, zero-padding the
--   encoding to 4 digits. This uses lowercase for the alphabetical digits.
--   For example, this encodes the number 1022 as <tt>03fe</tt>.
word16PaddedLowerHex :: Word16 -> Builder

-- | Encode a 16-bit unsigned integer as hexadecimal without leading
--   zeroes. This uses lowercase for the alphabetical digits. For example,
--   this encodes the number 1022 as <tt>3fe</tt>.
word16LowerHex :: Word16 -> Builder

-- | Encode a 16-bit unsigned integer as hexadecimal without leading
--   zeroes. This uses uppercase for the alphabetical digits. For example,
--   this encodes the number 1022 as <tt>3FE</tt>.
word16UpperHex :: Word16 -> Builder

-- | Encode a 8-bit unsigned integer as hexadecimal, zero-padding the
--   encoding to 2 digits. This uses uppercase for the alphabetical digits.
--   For example, this encodes the number 11 as <tt>0B</tt>.
word8PaddedUpperHex :: Word8 -> Builder

-- | Encode a 16-bit unsigned integer as hexadecimal without leading
--   zeroes. This uses lowercase for the alphabetical digits. For example,
--   this encodes the number 1022 as <tt>3FE</tt>.
word8LowerHex :: Word8 -> Builder

-- | Encode an ASCII char. Precondition: Input must be an ASCII character.
--   This is not checked.
ascii :: Char -> Builder

-- | Encode two ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii2 :: Char -> Char -> Builder

-- | Encode three ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii3 :: Char -> Char -> Char -> Builder

-- | Encode four ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii4 :: Char -> Char -> Char -> Char -> Builder

-- | Encode five ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii5 :: Char -> Char -> Char -> Char -> Char -> Builder

-- | Encode six ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii6 :: Char -> Char -> Char -> Char -> Char -> Char -> Builder

-- | Encode seven ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii7 :: Char -> Char -> Char -> Char -> Char -> Char -> Char -> Builder

-- | Encode eight ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii8 :: Char -> Char -> Char -> Char -> Char -> Char -> Char -> Char -> Builder

-- | Encode a UTF-8 char. This only uses as much space as is required.
char :: Char -> Builder

-- | Requires exactly 1 byte.
word8 :: Word8 -> Builder

-- | Requires exactly 32 bytes. Dump the octets of a 256-bit word in a
--   big-endian fashion.
word256BE :: Word256 -> Builder

-- | Requires exactly 16 bytes. Dump the octets of a 128-bit word in a
--   big-endian fashion.
word128BE :: Word128 -> Builder

-- | Requires exactly 8 bytes. Dump the octets of a 64-bit word in a
--   big-endian fashion.
word64BE :: Word64 -> Builder

-- | Requires exactly 4 bytes. Dump the octets of a 32-bit word in a
--   big-endian fashion.
word32BE :: Word32 -> Builder

-- | Requires exactly 2 bytes. Dump the octets of a 16-bit word in a
--   big-endian fashion.
word16BE :: Word16 -> Builder

-- | Requires exactly 8 bytes. Dump the octets of a 64-bit signed integer
--   in a big-endian fashion.
int64BE :: Int64 -> Builder

-- | Requires exactly 4 bytes. Dump the octets of a 32-bit signed integer
--   in a big-endian fashion.
int32BE :: Int32 -> Builder

-- | Requires exactly 2 bytes. Dump the octets of a 16-bit signed integer
--   in a big-endian fashion.
int16BE :: Int16 -> Builder

-- | Requires exactly 32 bytes. Dump the octets of a 256-bit word in a
--   little-endian fashion.
word256LE :: Word256 -> Builder

-- | Requires exactly 16 bytes. Dump the octets of a 128-bit word in a
--   little-endian fashion.
word128LE :: Word128 -> Builder

-- | Requires exactly 8 bytes. Dump the octets of a 64-bit word in a
--   little-endian fashion.
word64LE :: Word64 -> Builder

-- | Requires exactly 4 bytes. Dump the octets of a 32-bit word in a
--   little-endian fashion.
word32LE :: Word32 -> Builder

-- | Requires exactly 2 bytes. Dump the octets of a 16-bit word in a
--   little-endian fashion.
word16LE :: Word16 -> Builder

-- | Requires exactly 8 bytes. Dump the octets of a 64-bit signed integer
--   in a little-endian fashion.
int64LE :: Int64 -> Builder

-- | Requires exactly 4 bytes. Dump the octets of a 32-bit signed integer
--   in a little-endian fashion.
int32LE :: Int32 -> Builder

-- | Requires exactly 2 bytes. Dump the octets of a 16-bit signed integer
--   in a little-endian fashion.
int16LE :: Int16 -> Builder

-- | Encode a signed machine-sized integer with LEB-128. This uses zig-zag
--   encoding.
intLEB128 :: Int -> Builder

-- | Encode a 32-bit signed integer with LEB-128. This uses zig-zag
--   encoding.
int32LEB128 :: Int32 -> Builder

-- | Encode a 64-bit signed integer with LEB-128. This uses zig-zag
--   encoding.
int64LEB128 :: Int64 -> Builder

-- | Encode a machine-sized word with LEB-128.
wordLEB128 :: Word -> Builder

-- | Encode a 16-bit word with LEB-128.
word16LEB128 :: Word16 -> Builder

-- | Encode a 32-bit word with LEB-128.
word32LEB128 :: Word32 -> Builder

-- | Encode a 64-bit word with LEB-128.
word64LEB128 :: Word64 -> Builder

-- | Encode a machine-sized word with VLQ.
wordVlq :: Word -> Builder

-- | Encode a 32-bit word with VLQ.
word32Vlq :: Word32 -> Builder

-- | Encode a 64-bit word with VLQ.
word64Vlq :: Word64 -> Builder

-- | Create a builder from a slice of an array of <a>Word8</a>. There is
--   the same as <a>bytes</a> but is provided as a convenience for users
--   working with different types.
word8Array :: PrimArray Word8 -> Int -> Int -> Builder
word16ArrayBE :: PrimArray Word16 -> Int -> Int -> Builder
word32ArrayBE :: PrimArray Word32 -> Int -> Int -> Builder
word64ArrayBE :: PrimArray Word64 -> Int -> Int -> Builder
word128ArrayBE :: PrimArray Word128 -> Int -> Int -> Builder
word256ArrayBE :: PrimArray Word256 -> Int -> Int -> Builder
int64ArrayBE :: PrimArray Int64 -> Int -> Int -> Builder
int32ArrayBE :: PrimArray Int32 -> Int -> Int -> Builder
int16ArrayBE :: PrimArray Int16 -> Int -> Int -> Builder
word16ArrayLE :: PrimArray Word16 -> Int -> Int -> Builder
word32ArrayLE :: PrimArray Word32 -> Int -> Int -> Builder
word64ArrayLE :: PrimArray Word64 -> Int -> Int -> Builder
word128ArrayLE :: PrimArray Word128 -> Int -> Int -> Builder
word256ArrayLE :: PrimArray Word256 -> Int -> Int -> Builder
int64ArrayLE :: PrimArray Int64 -> Int -> Int -> Builder
int32ArrayLE :: PrimArray Int32 -> Int -> Int -> Builder
int16ArrayLE :: PrimArray Int16 -> Int -> Int -> Builder

-- | Prefix a builder with the number of bytes that it requires.
consLength :: Nat n -> (Int -> Builder n) -> Builder -> Builder

-- | Variant of <a>consLength32BE</a> the encodes the length in a
--   little-endian fashion.
consLength32LE :: Builder -> Builder

-- | Prefix a builder with its size in bytes. This size is presented as a
--   big-endian 32-bit word. The need to prefix a builder with its length
--   shows up a numbers of wire protocols including those of PostgreSQL and
--   Apache Kafka. Note the equivalence:
--   
--   <pre>
--   forall (n :: Int) (x :: Builder).
--     let sz = sizeofByteArray (run n (consLength32BE x))
--     consLength32BE x === word32BE (fromIntegral sz) &lt;&gt; x
--   </pre>
--   
--   However, using <a>consLength32BE</a> is much more efficient here since
--   it only materializes the <a>ByteArray</a> once.
consLength32BE :: Builder -> Builder

-- | Prefix a builder with its size in bytes. This size is presented as a
--   big-endian 64-bit word. See <a>consLength32BE</a>.
consLength64BE :: Builder -> Builder

-- | Encode a double-floating-point number, using decimal notation or
--   scientific notation depending on the magnitude. This has undefined
--   behavior when representing <tt>+inf</tt>, <tt>-inf</tt>, and
--   <tt>NaN</tt>. It will not crash, but the generated numbers will be
--   nonsense.
doubleDec :: Double -> Builder

-- | Replicate a byte the given number of times.
replicate :: Int -> Word8 -> Builder

-- | Push the buffer currently being filled onto the chunk list, allocating
--   a new active buffer of the requested size. This is helpful when a
--   small builder is sandwhiched between two large zero-copy builders:
--   
--   <pre>
--   insert bigA &lt;&gt; flush 1 &lt;&gt; word8 0x42 &lt;&gt; insert bigB
--   </pre>
--   
--   Without <tt>flush 1</tt>, <tt>word8 0x42</tt> would see the zero-byte
--   active buffer that <a>insert</a> returned, decide that it needed more
--   space, and allocate a 4080-byte buffer to which only a single byte
--   would be written.
flush :: Int -> Builder

-- | This function and the documentation for it are copied from Takano
--   Akio's fast-builder library.
--   
--   <tt><a>rebuild</a> b</tt> is equivalent to <tt>b</tt>, but it allows
--   GHC to assume that <tt>b</tt> will be run at most once. This can
--   enable various optimizations that greately improve performance.
--   
--   There are two types of typical situations where a use of
--   <a>rebuild</a> is often a win:
--   
--   <ul>
--   <li>When constructing a builder using a recursive function. e.g.
--   <tt>rebuild $ foldr ...</tt>.</li>
--   <li>When constructing a builder using a conditional expression. e.g.
--   <tt>rebuild $ case x of ... </tt></li>
--   </ul>
rebuild :: Builder -> Builder

module Data.Bytes.Builder.Class

-- | Types that can be encoded as a builder. Human-readable encodings are
--   used when possible. For example, numbers are encoded an ascii-encoded
--   decimal characters. UTF-8 is preferred for textual types. For types
--   that represent arbitrary bytes (e.g. Bytes, ByteString), the bytes are
--   preserved.
--   
--   The goal of this typeclass is to reduce the size of builders produced
--   by quasiquotation.
class ToBuilder a
toBuilder :: ToBuilder a => a -> Builder
instance Data.Bytes.Builder.Class.ToBuilder Data.Bytes.Builder.Unsafe.Builder
instance Data.Bytes.Builder.Class.ToBuilder Data.Bytes.Internal.Bytes
instance Data.Bytes.Builder.Class.ToBuilder Data.Array.Byte.ByteArray
instance Data.Bytes.Builder.Class.ToBuilder Data.ByteString.Short.Internal.ShortByteString
instance Data.Bytes.Builder.Class.ToBuilder Data.Text.Short.Internal.ShortText
instance Data.Bytes.Builder.Class.ToBuilder GHC.Base.String
instance Data.Bytes.Builder.Class.ToBuilder GHC.Int.Int64
instance Data.Bytes.Builder.Class.ToBuilder GHC.Int.Int32
instance Data.Bytes.Builder.Class.ToBuilder GHC.Int.Int16
instance Data.Bytes.Builder.Class.ToBuilder GHC.Int.Int8
instance Data.Bytes.Builder.Class.ToBuilder GHC.Types.Int
instance Data.Bytes.Builder.Class.ToBuilder GHC.Word.Word64
instance Data.Bytes.Builder.Class.ToBuilder GHC.Word.Word32
instance Data.Bytes.Builder.Class.ToBuilder GHC.Word.Word16
instance Data.Bytes.Builder.Class.ToBuilder GHC.Word.Word8
instance Data.Bytes.Builder.Class.ToBuilder GHC.Types.Word
instance Data.Bytes.Builder.Class.ToBuilder GHC.Types.Double


-- | Quasiquotation for byte builders.
module Data.Bytes.Builder.Template

-- | A quasiquoter for builders. Haskell expressions are interpolated with
--   backticks, and the <tt>ToBuilder</tt> class is used to convert them to
--   builders. Several common escape sequences for whitespace and control
--   characters are recongized. Consider the following expression, where
--   the binding <tt>partition</tt> has type <tt>Word32</tt>:
--   
--   <pre>
--   [templ|[WARN] Partition `partition` has invalid data.\n|]
--   </pre>
--   
--   This expression has type <tt>Builder</tt> and expands to:
--   
--   <pre>
--   Builder.cstringLen (Ptr "[WARN] Partition "#, 17) &lt;&gt;
--   Builder.toBuilder partition &lt;&gt;
--   Builder.cstringLen (Ptr " has invalid data.\n"#, 19)
--   </pre>
--   
--   The <tt>ToBuilder</tt> instance for <tt>Word32</tt> uses decimal
--   encoding, so this would result in the following if <tt>partition</tt>
--   was 42 (with a newline character at the end):
--   
--   <pre>
--   [WARN] Partition 42 has invalid data.
--   </pre>
--   
--   In the future, a more sophisticated <tt>bbldr</tt> variant will be
--   added that will support expressions where the maximum length of the
--   entire builder can be computed at compile time.
bldr :: QuasiQuoter


-- | Builders for encoding data with Apache Avro. Most functions in this
--   module are just aliases for other functions. Avro uses zig-zag LEB128
--   for all integral types.
module Data.Bytes.Builder.Avro
int :: Int -> Builder
int32 :: Int32 -> Builder
int64 :: Int64 -> Builder

-- | Note: This results in a zigzag encoded number. Avro does not have
--   unsigned types.
word16 :: Word16 -> Builder

-- | Note: This results in a zigzag encoded number. Avro does not have
--   unsigned types.
word32 :: Word32 -> Builder

-- | Note: This results in a <tt>fixed</tt> encoded value of length 16. In
--   the schema, the type must be <tt>{"type": "fixed", "name": "...",
--   "size": 16}</tt>. A big-endian encoding is used.
word128 :: Word128 -> Builder
bytes :: Bytes -> Builder
chunks :: Chunks -> Builder
text :: Text -> Builder

-- | Encode a map with exactly two key-value pairs. The keys are text. This
--   is commonly used to encode the header in an avro file, which has a map
--   with two keys: <tt>avro.schema</tt> and <tt>avro.codec</tt>.
map2 :: Text -> Builder -> Text -> Builder -> Builder