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


-- | Serialize to a small 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.5.0

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

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

-- | 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 64-bit word with LEB-128.
word64LEB128 :: 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.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 are 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
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 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

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

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

-- | 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 are be UTF-8
--   encoded.
stringUtf8 :: String -> 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 five ASCII characters. Precondition: Must be an ASCII
--   characters. This is not checked.
ascii6 :: 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 machine-sized word with LEB-128.
wordLEB128 :: Word -> Builder

-- | Encode a 64-bit word with LEB-128.
word64LEB128 :: 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

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