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

-- | Efficient buffered output.
--   
--   This library provides an abstraction of buffered output of byte
--   streams and several convenience functions to exploit it. For example,
--   it 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.
@package blaze-builder
@version 0.3.3.0

-- | Core types and functions for the Builder monoid and the
--   Put monad based based on the 'blaze-builder' library by Jasper
--   van der Jeugt and Simon Meier.
module Blaze.ByteString.Builder.Internal.Types
data BufRange
BufRange :: {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> BufRange
data BuildSignal a
Done :: {-# UNPACK #-} !(Ptr Word8) -> a -> BuildSignal a
BufferFull :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !(Ptr Word8) -> !(BuildStep a) -> BuildSignal a
InsertByteString :: {-# UNPACK #-} !(Ptr Word8) -> !ByteString -> !(BuildStep a) -> BuildSignal a
newtype BuildStep a
BuildStep :: (BufRange -> IO (BuildSignal a)) -> BuildStep a
runBuildStep :: BuildStep a -> BufRange -> IO (BuildSignal a)
done :: Ptr Word8 -> a -> BuildSignal a
bufferFull :: Int -> Ptr Word8 -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
insertByteString :: Ptr Word8 -> ByteString -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
buildStep :: (BufRange -> IO (BuildSignal a)) -> BuildStep a
newtype Builder
Builder :: (forall r. BuildStep r -> BuildStep r) -> Builder
unBuilder :: Builder -> forall r. BuildStep r -> BuildStep r
newtype Put a
Put :: (forall r. (a -> BuildStep r) -> BuildStep r) -> Put a
unPut :: Put a -> forall r. (a -> BuildStep r) -> BuildStep r
putBuildStepCont :: (forall r. (a -> BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Put a
fromBuildStepCont :: (forall r. (BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Builder

-- | Put the given builder.
putBuilder :: Builder -> Put ()

-- | Ignore the value of a put and only exploit its output side effect.
fromPut :: Put a -> Builder

-- | Lift the given IO action.
putLiftIO :: IO a -> Put a
instance Monad Put
instance Functor Put
instance Monoid Builder

-- | 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 explicitely but as part of a Write,
--   which also tells how many bytes will be changed at most.
data 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

-- | 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 Monoid Write
instance Monoid Poke

-- | Execution of the Put monad and hence also Builders with
--   respect to buffers.
module Blaze.ByteString.Builder.Internal.Buffer

-- | A buffer Buffer fpbuf p0 op ope describes a buffer with the
--   underlying byte array fpbuf..ope, the currently written slice
--   p0..op and the free space op..ope.
data Buffer
Buffer :: {-# UNPACK #-} !(ForeignPtr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> Buffer

-- | The size of the free space of the buffer.
freeSize :: Buffer -> Int

-- | The size of the written slice in the buffer.
sliceSize :: Buffer -> Int

-- | The size of the whole byte array underlying the buffer.
bufferSize :: Buffer -> Int

-- | allocBuffer size allocates a new buffer of size
--   size.
allocBuffer :: Int -> IO Buffer

-- | Resets the beginning of the next slice and the next free byte such
--   that the whole buffer can be filled again.
reuseBuffer :: Buffer -> Buffer

-- | Move the beginning of the slice to the next free byte such that the
--   remaining free space of the buffer can be filled further. This
--   operation is safe and can be used to fill the remaining part of the
--   buffer after a direct insertion of a bytestring or a flush.
nextSlice :: Int -> Buffer -> Maybe Buffer

-- | Update the end of slice pointer.
updateEndOfSlice :: Buffer -> Ptr Word8 -> Buffer

-- | Execute a build step on the given buffer.
execBuildStep :: BuildStep a -> Buffer -> IO (BuildSignal a)

-- | Convert the buffer to a bytestring. This operation is unsafe in the
--   sense that created bytestring shares the underlying byte array with
--   the buffer. Hence, depending on the later use of this buffer (e.g., if
--   it gets reset and filled again) referential transparency may be lost.
unsafeFreezeBuffer :: Buffer -> ByteString

-- | Convert a buffer to a non-empty bytestring. See
--   unsafeFreezeBuffer for the explanation of why this operation
--   may be unsafe.
unsafeFreezeNonEmptyBuffer :: Buffer -> Maybe ByteString

-- | A buffer allocation strategy (buf0, nextBuf) specifies the
--   initial buffer to use and how to compute a new buffer nextBuf
--   minSize buf with at least size minSize from a filled
--   buffer buf. The double nesting of the IO monad helps
--   to ensure that the reference to the filled buffer buf is lost
--   as soon as possible, but the new buffer doesn't have to be allocated
--   too early.
type BufferAllocStrategy = (IO Buffer, Int -> Buffer -> IO (IO Buffer))

-- | The simplest buffer allocation strategy: whenever a buffer is
--   requested, allocate a new one that is big enough for the next build
--   step to execute.
--   
--   NOTE that this allocation strategy may spill quite some memory upon
--   direct insertion of a bytestring by the builder. Thats no problem for
--   garbage collection, but it may lead to unreasonably high memory
--   consumption in special circumstances.
allNewBuffersStrategy :: Int -> BufferAllocStrategy

-- | An unsafe, but possibly more efficient buffer allocation strategy:
--   reuse the buffer, if it is big enough for the next build step to
--   execute.
reuseBufferStrategy :: IO Buffer -> BufferAllocStrategy

-- | Execute a put on a buffer.
--   
--   TODO: Generalize over buffer allocation strategy.
runPut :: Monad m => (IO (BuildSignal a) -> m (BuildSignal a)) -> (Int -> Buffer -> m Buffer) -> (ByteString -> m ()) -> Put a -> Buffer -> m (a, Buffer)

-- | Core types and functions for the Builder monoid and the
--   Put monad.
module Blaze.ByteString.Builder.Internal
data BufRange
BufRange :: {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> BufRange
data BuildSignal a
data BuildStep a
done :: Ptr Word8 -> a -> BuildSignal a
bufferFull :: Int -> Ptr Word8 -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
insertByteString :: Ptr Word8 -> ByteString -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
data Builder
fromBuildStepCont :: (forall r. (BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Builder

-- | Ignore the value of a put and only exploit its output side effect.
fromPut :: Put a -> Builder

-- | Output all data written in the current buffer and start a new chunk.
--   
--   The use of this function depends on how the resulting bytestrings are
--   consumed. flush is possibly not very useful in non-interactive
--   scenarios. However, it is kept for compatibility with the builder
--   provided by Data.Binary.Builder.
--   
--   When using toLazyByteString to extract a lazy ByteString
--   from a Builder, this means that a new chunk will be started in
--   the resulting lazy ByteString. The remaining part of the buffer
--   is spilled, if the reamining free space is smaller than the minimal
--   desired buffer size.
flush :: Builder
data Put a

-- | Put the given builder.
putBuilder :: Builder -> Put ()
putBuildStepCont :: (forall r. (a -> BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Put a

-- | Lift the given IO action.
putLiftIO :: IO a -> Put a

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

-- | Extract the lazy ByteString from the builder by running it with
--   default buffer sizes. Use this function, if you do not have any
--   special considerations with respect to buffer sizes.
--   
--   
--   toLazyByteString b = toLazyByteStringWith defaultBufferSize defaultMinimalBufferSize defaultFirstBufferSize b L.empty
--   
--   
--   Note that toLazyByteString is a Monoid
--   homomorphism.
--   
--   
--   toLazyByteString mempty          == mempty
--   toLazyByteString (x `mappend` y) == toLazyByteString x `mappend` toLazyByteString y
--   
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toLazyByteString :: Builder -> ByteString

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

-- | Run the builder with a defaultBufferSized buffer and execute
--   the given IO action whenever the buffer is full or gets
--   flushed.
--   
--   
--   toByteStringIO = toByteStringIOWith defaultBufferSize
--   
--   
--   This is a Monoid homomorphism in the following sense.
--   
--   
--   toByteStringIO io mempty          == return ()
--   toByteStringIO io (x `mappend` y) == toByteStringIO io x >> toByteStringIO io y
--   
toByteStringIO :: (ByteString -> IO ()) -> Builder -> IO ()

-- | 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.
toByteStringIOWith :: Int -> (ByteString -> IO ()) -> Builder -> IO ()

-- | The default length (64) for the first buffer to be allocated when
--   converting a Builder to a lazy bytestring.
--   
--   See toLazyByteStringWith for further explanation.
defaultFirstBufferSize :: Int

-- | The minimal length (~4kb) a buffer must have before filling it and
--   outputting it as a chunk of the output stream.
--   
--   This size determines when a buffer is spilled after a flush or
--   a direct bytestring insertion. It is also the size of the first chunk
--   generated by toLazyByteString.
defaultMinimalBufferSize :: Int

-- | Default size (~32kb) for the buffer that becomes a chunk of the output
--   stream once it is filled.
defaultBufferSize :: Int

-- | The maximal number of bytes for that copying is cheaper than direct
--   insertion into the output stream. This takes into account the
--   fragmentation that may occur in the output buffer due to the early
--   flush implied by the direct bytestring insertion.
--   
--   
--   defaultMaximalCopySize = 2 * defaultMinimalBufferSize
--   
defaultMaximalCopySize :: Int

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

-- | Smart serialization of a strict bytestring.
--   
--   
--   fromByteString = fromByteStringWith defaultMaximalCopySize
--   
--   
--   Use this function to serialize strict bytestrings. It guarantees an
--   average chunk size of 4kb, which has been shown to be a reasonable
--   size in benchmarks. Note that the check whether to copy or to insert
--   is (almost) free as the builder performance is mostly memory-bound.
--   
--   If you statically know that copying or inserting the strict bytestring
--   is always the best choice, then you can use the copyByteString
--   or insertByteString functions.
fromByteString :: ByteString -> Builder

-- | fromByteStringWith maximalCopySize bs serializes the strict
--   bytestring bs according to the following rules.
--   
--   
--   
- S.length bs <= maximalCopySize: bs is
--   copied to the output buffer.
--   
- S.length bs > maximalCopySize: bs the
--   output buffer is flushed and bs is inserted directly as
--   separate chunk in the output stream.
--   
--   
--   These rules guarantee that average chunk size in the output stream is
--   at least half the maximalCopySize.
fromByteStringWith :: Int -> ByteString -> Builder

-- | copyByteString bs serialize the strict bytestring bs
--   by copying it to the output buffer.
--   
--   Use this function to serialize strict bytestrings that are statically
--   known to be smallish (<= 4kb).
copyByteString :: ByteString -> Builder

-- | insertByteString bs serializes the strict bytestring
--   bs by inserting it directly as a chunk of the output stream.
--   
--   Note that this implies flushing the output buffer; even if it contains
--   just a single byte. Hence, you should use this operation only for
--   large (> 8kb) bytestrings, as otherwise the resulting
--   output stream may be too fragmented to be processed efficiently.
insertByteString :: ByteString -> Builder

-- | O(n). Smart serialization of a lazy bytestring.
--   
--   
--   fromLazyByteString = fromLazyByteStringWith defaultMaximalCopySize
--   
--   
--   Use this function to serialize lazy bytestrings. It guarantees an
--   average chunk size of 4kb, which has been shown to be a reasonable
--   size in benchmarks. Note that the check whether to copy or to insert
--   is (almost) free as the builder performance is mostly memory-bound.
--   
--   If you statically know that copying or inserting all chunks of
--   the lazy bytestring is always the best choice, then you can use the
--   copyLazyByteString or insertLazyByteString functions.
fromLazyByteString :: ByteString -> Builder

-- | O(n). Serialize a lazy bytestring chunk-wise according to the
--   same rules as in fromByteStringWith.
--   
--   Semantically, it holds that
--   
--   
--     fromLazyByteStringWith maxCopySize
--   = mconcat . map (fromByteStringWith maxCopySize) . L.toChunks
--   
--   
--   However, the left-hand-side is much more efficient, as it moves the
--   end-of-buffer pointer out of the inner loop and provides the compiler
--   with more strictness information.
fromLazyByteStringWith :: Int -> ByteString -> Builder

-- | O(n). Serialize a lazy bytestring by copying all chunks
--   sequentially to the output buffer.
--   
--   See copyByteString for usage considerations.
copyLazyByteString :: ByteString -> Builder

-- | O(n). Serialize a lazy bytestring by inserting all its
--   chunks directly into the output stream.
--   
--   See insertByteString for usage considerations.
--   
--   For library developers, see the ModifyChunks build signal, if
--   you need an O(1) lazy bytestring insert based on difference
--   lists.
insertLazyByteString :: ByteString -> 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 little 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 Word32 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 list of Word64s in native host order and host
--   endianness.
fromWord64shost :: [Word64] -> 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

-- | Support for HTTP response encoding.
--   
--   TODO: Improve documentation.
module Blaze.ByteString.Builder.HTTP

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

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

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

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

-- | Output all data written in the current buffer and start a new chunk.
--   
--   The use of this function depends on how the resulting bytestrings are
--   consumed. flush is possibly not very useful in non-interactive
--   scenarios. However, it is kept for compatibility with the builder
--   provided by Data.Binary.Builder.
--   
--   When using toLazyByteString to extract a lazy ByteString
--   from a Builder, this means that a new chunk will be started in
--   the resulting lazy ByteString. The remaining part of the buffer
--   is spilled, if the reamining free space is smaller than the minimal
--   desired buffer size.
flush :: Builder

-- | Extract the lazy ByteString from the builder by running it with
--   default buffer sizes. Use this function, if you do not have any
--   special considerations with respect to buffer sizes.
--   
--   
--   toLazyByteString b = toLazyByteStringWith defaultBufferSize defaultMinimalBufferSize defaultFirstBufferSize b L.empty
--   
--   
--   Note that toLazyByteString is a Monoid
--   homomorphism.
--   
--   
--   toLazyByteString mempty          == mempty
--   toLazyByteString (x `mappend` y) == toLazyByteString x `mappend` toLazyByteString y
--   
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toLazyByteString :: Builder -> ByteString

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

-- | Run the builder with a defaultBufferSized buffer and execute
--   the given IO action whenever the buffer is full or gets
--   flushed.
--   
--   
--   toByteStringIO = toByteStringIOWith defaultBufferSize
--   
--   
--   This is a Monoid homomorphism in the following sense.
--   
--   
--   toByteStringIO io mempty          == return ()
--   toByteStringIO io (x `mappend` y) == toByteStringIO io x >> toByteStringIO io y
--   
toByteStringIO :: (ByteString -> IO ()) -> Builder -> IO ()

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

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