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

-- | Efficient buffered output.
--   
--   This library allows to efficiently serialize Haskell values to lazy
--   bytestrings with a large average chunk size. The large average chunk
--   size allows to make good use of cache prefetching in later processing
--   steps (e.g. compression) and reduces the system call overhead when
--   writing the resulting lazy bytestring to a file or sending it over the
--   network.
--   
--   This library was inspired by the module Data.Binary.Builder provided
--   by the binary package. It was originally developed with the specific
--   needs of the blaze-html package in mind. Since then it has been
--   restructured to serve as a drop-in replacement for
--   Data.Binary.Builder, which it improves upon both in speed as well as
--   expressivity.
@package blaze-builder
@version 0.4.4.1

-- | A general and efficient write type that allows for the easy
--   construction of builders for (smallish) bounded size writes to a
--   buffer.
--   
--   FIXME: Improve documentation.
module Blaze.ByteString.Builder.Internal.Write

-- | Changing a sequence of bytes starting from the given pointer.
--   Pokes are the most primitive buffer manipulation. In most
--   cases, you don't use the explicitly but as part of a Write,
--   which also tells how many bytes will be changed at most.
newtype Poke
Poke :: (Ptr Word8 -> IO (Ptr Word8)) -> Poke
[runPoke] :: Poke -> Ptr Word8 -> IO (Ptr Word8)

-- | pokeN size io creates a write that denotes the writing of
--   size bytes to a buffer using the IO action io. Note
--   that io MUST write EXACTLY size bytes to the buffer!
pokeN :: Int -> (Ptr Word8 -> IO ()) -> Poke

-- | A write of a bounded number of bytes.
--   
--   When defining a function write :: a -> Write for some
--   a, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   
--   forall x y. getBound (write x) = getBound (write y)
--   
--   
--   The idea is that this data-independent bound is specified such that
--   the compiler can optimize the check, if there are enough free bytes in
--   the buffer, to a single subtraction between the pointer to the next
--   free byte and the pointer to the end of the buffer with this constant
--   bound of the maximal number of bytes to be written.
data Write
Write :: {-# UNPACK #-} !Int -> Poke -> Write

-- | Run the Poke action of a write.
runWrite :: Write -> Ptr Word8 -> IO (Ptr Word8)

-- | Extract the maximal number of bytes that this write could write.
getBound :: Write -> Int

-- | Extract the maximal number of bytes that this write could write in any
--   case. Assumes that the bound of the write is data-independent.
getBound' :: String -> (a -> Write) -> Int

-- | Extract the Poke action of a write.
getPoke :: Write -> Poke

-- | exactWrite size io creates a bounded write that can later be
--   converted to a builder that writes exactly size bytes. Note
--   that io MUST write EXACTLY size bytes to the buffer!
exactWrite :: Int -> (Ptr Word8 -> IO ()) -> Write

-- | boundedWrite size write creates a bounded write from a
--   write that does not write more than size bytes.
boundedWrite :: Int -> Poke -> Write

-- | writeLiftIO io write creates a write executes the io
--   action to compute the value that is then written.
writeLiftIO :: (a -> Write) -> IO a -> Write

-- | writeIf p wTrue wFalse x creates a Write with a
--   Poke equal to wTrue x, if p x and equal to
--   wFalse x otherwise. The bound of this new Write is the
--   maximum of the bounds for either Write. This yields a data
--   independent bound, if the bound for wTrue and wFalse
--   is already data independent.
writeIf :: (a -> Bool) -> (a -> Write) -> (a -> Write) -> a -> Write

-- | Compare the value to a test value and use the first write action for
--   the equal case and the second write action for the non-equal case.
writeEq :: Eq a => a -> (a -> Write) -> (a -> Write) -> a -> Write

-- | TODO: Test this. It might well be too difficult to use. FIXME: Better
--   name required!
writeOrdering :: (a -> Ordering) -> (a -> Write) -> (a -> Write) -> (a -> Write) -> a -> Write

-- | A write combinator useful to build decision trees for deciding what
--   value to write with a constant bound on the maximal number of bytes
--   written.
writeOrd :: Ord a => a -> (a -> Write) -> (a -> Write) -> (a -> Write) -> a -> Write

-- | Create a builder that execute a single Write.
fromWrite :: Write -> Builder
fromWriteSingleton :: (a -> Write) -> a -> Builder

-- | Construct a Builder writing a list of data one element at a
--   time.
fromWriteList :: (a -> Write) -> [a] -> Builder

-- | Write a storable value.
writeStorable :: Storable a => a -> Write

-- | A builder that serializes a storable value. No alignment is done.
fromStorable :: Storable a => a -> Builder

-- | A builder that serializes a list of storable values by writing them
--   consecutively. No alignment is done. Parsing information needs to be
--   provided externally.
fromStorables :: Storable a => [a] -> Builder
instance GHC.Internal.Base.Monoid Blaze.ByteString.Builder.Internal.Write.Poke
instance GHC.Internal.Base.Monoid Blaze.ByteString.Builder.Internal.Write.Write
instance GHC.Internal.Base.Semigroup Blaze.ByteString.Builder.Internal.Write.Poke
instance GHC.Internal.Base.Semigroup Blaze.ByteString.Builder.Internal.Write.Write

-- | Conversions from the new Prims to the old Writes.
module Blaze.ByteString.Builder.Compat.Write

-- | A write of a bounded number of bytes.
--   
--   When defining a function write :: a -> Write for some
--   a, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   
--   forall x y. getBound (write x) = getBound (write y)
--   
--   
--   The idea is that this data-independent bound is specified such that
--   the compiler can optimize the check, if there are enough free bytes in
--   the buffer, to a single subtraction between the pointer to the next
--   free byte and the pointer to the end of the buffer with this constant
--   bound of the maximal number of bytes to be written.
data Write
writePrimFixed :: FixedPrim a -> a -> Write
writePrimBounded :: BoundedPrim a -> a -> Write

-- | Writes and Builders for serializing integers.
--   
--   See Blaze.ByteString.Builder.Word for information about how to
--   best write several integers at once.
module Blaze.ByteString.Builder.Int

-- | Write a single signed byte.
writeInt8 :: Int8 -> Write

-- | Write an Int16 in big endian format.
writeInt16be :: Int16 -> Write

-- | Write an Int32 in big endian format.
writeInt32be :: Int32 -> Write

-- | Write an Int64 in big endian format.
writeInt64be :: Int64 -> Write

-- | Write an Int16 in little endian format.
writeInt16le :: Int16 -> Write

-- | Write an Int32 in little endian format.
writeInt32le :: Int32 -> Write

-- | Write an Int64 in little endian format.
writeInt64le :: Int64 -> Write

-- | Write a single native machine Int. The Int is written in
--   host order, host endian form, for the machine you're on. On a 64 bit
--   machine the Int is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values written this way are not portable to different endian or
--   integer sized machines, without conversion.
writeInthost :: Int -> Write

-- | Write an Int16 in native host order and host endianness.
writeInt16host :: Int16 -> Write

-- | Write an Int32 in native host order and host endianness.
writeInt32host :: Int32 -> Write

-- | Write an Int64 in native host order and host endianness.
writeInt64host :: Int64 -> Write

-- | Serialize a single byte.
fromInt8 :: Int8 -> Builder

-- | Serialize a list of bytes.
fromInt8s :: [Int8] -> Builder

-- | Serialize an Int16 in big endian format.
fromInt16be :: Int16 -> Builder

-- | Serialize an Int32 in big endian format.
fromInt32be :: Int32 -> Builder

-- | Serialize an Int64 in big endian format.
fromInt64be :: Int64 -> Builder

-- | Serialize a list of Int32s in big endian format.
fromInt32sbe :: [Int32] -> Builder

-- | Serialize a list of Int16s in big endian format.
fromInt16sbe :: [Int16] -> Builder

-- | Serialize a list of Int64s in big endian format.
fromInt64sbe :: [Int64] -> Builder

-- | Serialize an Int16 in little endian format.
fromInt16le :: Int16 -> Builder

-- | Serialize an Int32 in little endian format.
fromInt32le :: Int32 -> Builder

-- | Serialize an Int64 in little endian format.
fromInt64le :: Int64 -> Builder

-- | Serialize a list of Int16s in little endian format.
fromInt16sle :: [Int16] -> Builder

-- | Serialize a list of Int32s in little endian format.
fromInt32sle :: [Int32] -> Builder

-- | Serialize a list of Int64s in little endian format.
fromInt64sle :: [Int64] -> Builder

-- | Serialize a single native machine Int. The Int is
--   serialized in host order, host endian form, for the machine you're on.
--   On a 64 bit machine the Int is an 8 byte value, on a 32 bit
--   machine, 4 bytes. Values written this way are not portable to
--   different endian or integer sized machines, without conversion.
fromInthost :: Int -> Builder

-- | Write an Int16 in native host order and host endianness.
fromInt16host :: Int16 -> Builder

-- | Write an Int32 in native host order and host endianness.
fromInt32host :: Int32 -> Builder

-- | Write an Int64 in native host order and host endianness.
fromInt64host :: Int64 -> Builder

-- | Serialize a list of Ints. See fromInthost for usage
--   considerations.
fromIntshost :: [Int] -> Builder

-- | Write a list of Int16s in native host order and host
--   endianness.
fromInt16shost :: [Int16] -> Builder

-- | Write a list of Int32s in native host order and host
--   endianness.
fromInt32shost :: [Int32] -> Builder

-- | Write a list of Int64s in native host order and host
--   endianness.
fromInt64shost :: [Int64] -> Builder

-- | Writes and Builders for serializing HTML escaped
--   Word8 characters and ByteStrings that have already been
--   appropriately encoded into HTML by escaping basic ASCII character
--   references but leaving other bytes untouched.
module Blaze.ByteString.Builder.Html.Word
wordHtmlEscaped :: BoundedPrim Word8

-- | Write a HTML escaped byte to a bufffer.
writeHtmlEscapedWord :: Word8 -> Write

-- | O(1). Serialize a HTML escaped byte.
fromHtmlEscapedWord :: Word8 -> Builder

-- | O(n). Serialize a HTML escaped list of bytes.
fromHtmlEscapedWordList :: [Word8] -> Builder

-- | O(n). Serialize a HTML escaped ByteString.
fromHtmlEscapedByteString :: ByteString -> Builder

-- | O(n). Serialize a HTML escaped lazy ByteString.
fromHtmlEscapedLazyByteString :: ByteString -> Builder

-- | /Note:/ This package is intended for low-level use like
--   implementing protocols. If you need to /serialize/ Unicode
--   characters use one of the UTF encodings (e.g.
--   'Blaze.ByteString.Builder.Char.UTF-8').
--   
--   Writes and Builders for serializing the lower 8-bits of
--   characters.
--   
--   This corresponds to what the bytestring package offer in
--   Char8.
module Blaze.ByteString.Builder.Char8

-- | Write the lower 8-bits of a character to a buffer.
writeChar :: Char -> Write

-- | O(1). Serialize the lower 8-bits of a character.
fromChar :: Char -> Builder

-- | O(n). Serialize the lower 8-bits of all characters of a string
fromString :: String -> Builder

-- | O(n). Serialize a value by Showing it and serializing
--   the lower 8-bits of the resulting string.
fromShow :: Show a => a -> Builder

-- | O(n). Serialize the lower 8-bits of all characters in the
--   strict text.
fromText :: Text -> Builder

-- | O(n). Serialize the lower 8-bits of all characters in the lazy
--   text.
fromLazyText :: Text -> Builder

-- | Writes and Builders for serializing Unicode characters
--   using the UTF-8 encoding.
module Blaze.ByteString.Builder.Char.Utf8

-- | Write a UTF-8 encoded Unicode character to a buffer.
writeChar :: Char -> Write

-- | O(1). Serialize a Unicode character using the UTF-8 encoding.
fromChar :: Char -> Builder

-- | O(n). Serialize a Unicode String using the UTF-8
--   encoding.
fromString :: String -> Builder

-- | O(n). Serialize a value by Showing it and UTF-8 encoding
--   the resulting String.
fromShow :: Show a => a -> Builder

-- | O(n). Serialize a strict Unicode Text value using the
--   UTF-8 encoding.
fromText :: Text -> Builder

-- | O(n). Serialize a lazy Unicode Text value using the
--   UTF-8 encoding.
fromLazyText :: Text -> Builder

-- | Writes and Builders for serializing HTML escaped and
--   UTF-8 encoded characters.
--   
--   This module is used by both the 'blaze-html' and the 'hamlet' HTML
--   templating libraries. If the Builder from 'blaze-builder'
--   replaces the Builder implementation, this module will most
--   likely keep its place, as it provides a set of very specialized
--   functions.
module Blaze.ByteString.Builder.Html.Utf8

-- | Write a HTML escaped and UTF-8 encoded Unicode character to a bufffer.
writeHtmlEscapedChar :: Char -> Write

-- | O(1). Serialize a HTML escaped Unicode character using the
--   UTF-8 encoding.
fromHtmlEscapedChar :: Char -> Builder

-- | O(n). Serialize a HTML escaped Unicode String using the
--   UTF-8 encoding.
fromHtmlEscapedString :: String -> Builder

-- | O(n). Serialize a value by Showing it and then, HTML
--   escaping and UTF-8 encoding the resulting String.
fromHtmlEscapedShow :: Show a => a -> Builder

-- | O(n). Serialize a HTML escaped strict Unicode Text value
--   using the UTF-8 encoding.
fromHtmlEscapedText :: Text -> Builder

-- | O(n). Serialize a HTML escaped Unicode Text using the
--   UTF-8 encoding.
fromHtmlEscapedLazyText :: Text -> Builder

-- | Writes and Builders for strict and lazy bytestrings.
--   
--   We assume the following qualified imports in order to differentiate
--   between strict and lazy bytestrings in the code examples.
--   
--   
--   import qualified Data.ByteString      as S
--   import qualified Data.ByteString.Lazy as L
--   
module Blaze.ByteString.Builder.ByteString

-- | Write a strict ByteString to a buffer.
writeByteString :: ByteString -> Write

-- | Create a Builder denoting the same sequence of bytes as a
--   strict ByteString. The Builder inserts large
--   ByteStrings directly, but copies small ones to ensure that the
--   generated chunks are large on average.
fromByteString :: ByteString -> Builder

-- | Construct a Builder that copies the strict ByteStrings,
--   if it is smaller than the threshold, and inserts it directly
--   otherwise.
--   
--   For example, fromByteStringWith 1024 copies strict
--   ByteStrings whose size is less or equal to 1kb, and inserts
--   them directly otherwise. This implies that the average chunk-size of
--   the generated lazy ByteString may be as low as 513 bytes, as
--   there could always be just a single byte between the directly inserted
--   1025 byte, strict ByteStrings.
fromByteStringWith :: Int -> ByteString -> Builder

-- | Construct a Builder that copies the strict ByteString.
--   
--   Use this function to create Builders from smallish (<=
--   4kb) ByteStrings or if you need to guarantee that the
--   ByteString is not shared with the chunks generated by the
--   Builder.
copyByteString :: ByteString -> Builder

-- | Construct a Builder that always inserts the strict
--   ByteString directly as a chunk.
--   
--   This implies flushing the output buffer, even if it contains just a
--   single byte. You should therefore use insertByteString only for
--   large (> 8kb) ByteStrings. Otherwise, the generated
--   chunks are too fragmented to be processed efficiently afterwards.
insertByteString :: ByteString -> Builder

-- | Create a Builder denoting the same sequence of bytes as a lazy
--   ByteString. The Builder inserts large chunks of the lazy
--   ByteString directly, but copies small ones to ensure that the
--   generated chunks are large on average.
fromLazyByteString :: ByteString -> Builder

-- | Construct a Builder that uses the thresholding strategy of
--   fromByteStringWith for each chunk of the lazy
--   ByteString.
fromLazyByteStringWith :: Int -> ByteString -> Builder

-- | Construct a Builder that copies the lazy ByteString.
copyLazyByteString :: ByteString -> Builder

-- | Construct a Builder that inserts all chunks of the lazy
--   ByteString directly.
insertLazyByteString :: ByteString -> Builder

-- | Support for HTTP response encoding.
module Blaze.ByteString.Builder.HTTP

-- | Transform a builder such that it uses chunked HTTP transfer encoding.
chunkedTransferEncoding :: Builder -> Builder

-- | The zero-length chunk '0rnrn' signaling the termination of the data
--   transfer.
chunkedTransferTerminator :: Builder

-- | Writes and Builders for serializing words.
--   
--   Note that for serializing a three tuple (x,y,z) of bytes (or
--   other word values) you should use the expression
--   
--   
--   fromWrite $ writeWord8 x `mappend` writeWord8 y `mappend` writeWord z
--   
--   
--   instead of
--   
--   
--   fromWord8 x `mappend` fromWord8 y `mappend` fromWord z
--   
--   
--   The first expression will result in a single atomic write of three
--   bytes, while the second expression will check for each byte, if there
--   is free space left in the output buffer. Coalescing these checks can
--   improve performance quite a bit, as long as you use it sensibly.
module Blaze.ByteString.Builder.Word

-- | Write a single byte.
writeWord8 :: Word8 -> Write

-- | Write a Word16 in big endian format.
writeWord16be :: Word16 -> Write

-- | Write a Word32 in big endian format.
writeWord32be :: Word32 -> Write

-- | Write a Word64 in big endian format.
writeWord64be :: Word64 -> Write

-- | Write a Word16 in little endian format.
writeWord16le :: Word16 -> Write

-- | Write a Word32 in big endian format.
writeWord32le :: Word32 -> Write

-- | Write a Word64 in little endian format.
writeWord64le :: Word64 -> Write

-- | Write a single native machine Word. The Word is written
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the Word is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values written this way are not portable to different endian or
--   word sized machines, without conversion.
writeWordhost :: Word -> Write

-- | Write a Word16 in native host order and host endianness.
writeWord16host :: Word16 -> Write

-- | Write a Word32 in native host order and host endianness.
writeWord32host :: Word32 -> Write

-- | Write a Word64 in native host order and host endianness.
writeWord64host :: Word64 -> Write

-- | Serialize a single byte.
fromWord8 :: Word8 -> Builder

-- | Serialize a list of bytes.
fromWord8s :: [Word8] -> Builder

-- | Serialize a Word16 in big endian format.
fromWord16be :: Word16 -> Builder

-- | Serialize a Word32 in big endian format.
fromWord32be :: Word32 -> Builder

-- | Serialize a Word64 in big endian format.
fromWord64be :: Word64 -> Builder

-- | Serialize a list of Word32s in big endian format.
fromWord32sbe :: [Word32] -> Builder

-- | Serialize a list of Word16s in big endian format.
fromWord16sbe :: [Word16] -> Builder

-- | Serialize a list of Word64s in big endian format.
fromWord64sbe :: [Word64] -> Builder

-- | Serialize a Word16 in little endian format.
fromWord16le :: Word16 -> Builder

-- | Serialize a list of Word32s in little endian format.
fromWord32le :: Word32 -> Builder

-- | Serialize a Word64 in little endian format.
fromWord64le :: Word64 -> Builder

-- | Serialize a list of Word16s in little endian format.
fromWord16sle :: [Word16] -> Builder

-- | Serialize a list of Word32s in little endian format.
fromWord32sle :: [Word32] -> Builder

-- | Serialize a list of Word64s in little endian format.
fromWord64sle :: [Word64] -> Builder

-- | Serialize a single native machine Word. The Word is
--   serialized in host order, host endian form, for the machine you're on.
--   On a 64 bit machine the Word is an 8 byte value, on a 32 bit
--   machine, 4 bytes. Values written this way are not portable to
--   different endian or word sized machines, without conversion.
fromWordhost :: Word -> Builder

-- | Write a Word16 in native host order and host endianness.
fromWord16host :: Word16 -> Builder

-- | Write a Word32 in native host order and host endianness.
fromWord32host :: Word32 -> Builder

-- | Write a Word64 in native host order and host endianness.
fromWord64host :: Word64 -> Builder

-- | Serialize a list of Words. See fromWordhost for usage
--   considerations.
fromWordshost :: [Word] -> Builder

-- | Write a list of Word16s in native host order and host
--   endianness.
fromWord16shost :: [Word16] -> Builder

-- | Write a list of Word32s in native host order and host
--   endianness.
fromWord32shost :: [Word32] -> Builder

-- | Write a Word64 in native host order and host endianness.
fromWord64shost :: [Word64] -> Builder

-- | Blaze.ByteString.Builder is the main module, which you should
--   import as a user of the blaze-builder library.
--   
--   
--   import Blaze.ByteString.Builder
--   
--   
--   It provides you with a type Builder that allows to efficiently
--   construct lazy bytestrings with a large average chunk size.
--   
--   Intuitively, a Builder denotes the construction of a part of a
--   lazy bytestring. Builders can either be created using one of the
--   primitive combinators in Blaze.ByteString.Builder.Write or by
--   using one of the predefined combinators for standard Haskell values
--   (see the exposed modules of this package). Concatenation of builders
--   is done using mappend from the Monoid typeclass.
--   
--   Here is a small example that serializes a list of strings using the
--   UTF-8 encoding.
--   
--   
--   import Blaze.ByteString.Builder.Char.Utf8
--   
--   
--   
--   strings :: [String]
--   strings = replicate 10000 "Hello there!"
--   
--   
--   The function fromString creates a Builder
--   denoting the UTF-8 encoded argument. Hence, UTF-8 encoding and
--   concatenating all strings can be done follows.
--   
--   
--   concatenation :: Builder
--   concatenation = mconcat $ map fromString strings
--   
--   
--   The function toLazyByteString can be used to execute a
--   Builder and obtain the resulting lazy bytestring.
--   
--   
--   result :: L.ByteString
--   result = toLazyByteString concatenation
--   
--   
--   The result is a lazy bytestring containing 10000 repetitions
--   of the string "Hello there!" encoded using UTF-8. The
--   corresponding 120000 bytes are distributed among three chunks of 32kb
--   and a last chunk of 6kb.
--   
--   A note on history. This serialization library was inspired by
--   the Data.Binary.Builder module provided by the
--   binary package. It was originally developed with the specific
--   needs of the blaze-html package in mind. Since then it has
--   been restructured to serve as a drop-in replacement for
--   Data.Binary.Builder, which it improves upon both in speed as
--   well as expressivity.
module Blaze.ByteString.Builder

-- | Builders denote sequences of bytes. They are Monoids
--   where mempty is the zero-length sequence and mappend is
--   concatenation, which runs in O(1).
data Builder

-- | Flush the current buffer. This introduces a chunk boundary.
flush :: Builder

-- | Execute a Builder and return the generated chunks as a
--   LazyByteString. The work is performed lazy, i.e., only when a
--   chunk of the LazyByteString is forced.
toLazyByteString :: Builder -> LazyByteString

-- | Run a Builder with the given buffer sizes.
--   
--   Use this function for integrating the Builder type with other
--   libraries that generate lazy bytestrings.
--   
--   Note that the builders should guarantee that on average the desired
--   chunk size is attained. Builders may decide to start a new buffer and
--   not completely fill the existing buffer, if this is faster. However,
--   they should not spill too much of the buffer, if they cannot
--   compensate for it.
--   
--   FIXME: Note that the following paragraphs are not entirely correct as
--   of blaze-builder-0.4:
--   
--   A call toLazyByteStringWith bufSize minBufSize firstBufSize
--   will generate a lazy bytestring according to the following strategy.
--   First, we allocate a buffer of size firstBufSize and start
--   filling it. If it overflows, we allocate a buffer of size
--   minBufSize and copy the first buffer to it in order to avoid
--   generating a too small chunk. Finally, every next buffer will be of
--   size bufSize. This, slow startup strategy is required to
--   achieve good speed for short (<200 bytes) resulting bytestrings, as
--   for them the allocation cost is of a large buffer cannot be
--   compensated. Moreover, this strategy also allows us to avoid spilling
--   too much memory for short resulting bytestrings.
--   
--   Note that setting firstBufSize >= minBufSize implies that
--   the first buffer is no longer copied but allocated and filled
--   directly. Hence, setting firstBufSize = bufSize means that
--   all chunks will use an underlying buffer of size bufSize.
--   This is recommended, if you know that you always output more than
--   minBufSize bytes.
toLazyByteStringWith :: Int -> Int -> Int -> Builder -> ByteString -> ByteString

-- | Run the builder to construct a strict bytestring containing the
--   sequence of bytes denoted by the builder. This is done by first
--   serializing to a lazy bytestring and then packing its chunks to a
--   appropriately sized strict bytestring.
--   
--   
--   toByteString = packChunks . toLazyByteString
--   
--   
--   Note that toByteString is a Monoid
--   homomorphism.
--   
--   
--   toByteString mempty          == mempty
--   toByteString (x `mappend` y) == toByteString x `mappend` toByteString y
--   
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toByteString :: Builder -> ByteString

-- | toByteStringIOWith bufSize io b runs the builder b
--   with a buffer of at least the size bufSize and executes the
--   IO action io whenever the buffer is full.
--   
--   Compared to toLazyByteStringWith this function requires less
--   allocation, as the output buffer is only allocated once at the start
--   of the serialization and whenever something bigger than the current
--   buffer size has to be copied into the buffer, which should happen very
--   seldomly for the default buffer size of 32kb. Hence, the pressure on
--   the garbage collector is reduced, which can be an advantage when
--   building long sequences of bytes.
toByteStringIO :: (ByteString -> IO ()) -> Builder -> IO ()
toByteStringIOWith :: Int -> (ByteString -> IO ()) -> Builder -> IO ()

-- | A write of a bounded number of bytes.
--   
--   When defining a function write :: a -> Write for some
--   a, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   
--   forall x y. getBound (write x) = getBound (write y)
--   
--   
--   The idea is that this data-independent bound is specified such that
--   the compiler can optimize the check, if there are enough free bytes in
--   the buffer, to a single subtraction between the pointer to the next
--   free byte and the pointer to the end of the buffer with this constant
--   bound of the maximal number of bytes to be written.
data Write

-- | Create a builder that execute a single Write.
fromWrite :: Write -> Builder
fromWriteSingleton :: (a -> Write) -> a -> Builder

-- | Construct a Builder writing a list of data one element at a
--   time.
fromWriteList :: (a -> Write) -> [a] -> Builder

-- | Run a Write to produce a strict ByteString. This is
--   equivalent to (toByteString . fromWrite), but
--   is more efficient because it uses just one appropriately-sized buffer.
writeToByteString :: Write -> ByteString

-- | Write a storable value.
writeStorable :: Storable a => a -> Write

-- | A builder that serializes a storable value. No alignment is done.
fromStorable :: Storable a => a -> Builder

-- | A builder that serializes a list of storable values by writing them
--   consecutively. No alignment is done. Parsing information needs to be
--   provided externally.
fromStorables :: Storable a => [a] -> Builder
