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


-- | Enumeratees for the incremental conversion of builders to
--   bytestrings.
--   
--   This package integrates the builders from the blaze-builder package
--   with the enumerator package. It provides infrastructure and
--   enumeratees for incrementally executing builders and pass the filled
--   chunks to a bytestring iteratee.
@package blaze-builder-enumerator
@version 0.2.1.0


-- | Infrastructure and enumeratees for the incremental execution of
--   builders and passing on of the filled chunks as bytestrings to an
--   inner iteratee.
--   
--   Note that the <tt>Buffer</tt> code is likely to move/change in order
--   to reconciliate it with the rest of the blaze-builder library.
module Blaze.ByteString.Builder.Enumerator

-- | A buffer <tt>Buffer fpbuf p0 op ope</tt> describes a buffer with the
--   underlying byte array <tt>fpbuf..ope</tt>, the currently written slice
--   <tt>p0..op</tt> and the free space <tt>op..ope</tt>.
--   
--   Since 0.1.10.0
data Buffer :: *

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

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

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

-- | <tt>allocBuffer size</tt> allocates a new buffer of size
--   <tt>size</tt>.
--   
--   Since 0.1.10.0
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.
--   
--   Since 0.1.10.0
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.
--   
--   Since 0.1.10.0
nextSlice :: Int -> Buffer -> Maybe Buffer

-- | 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.
--   
--   Since 0.1.10.0
unsafeFreezeBuffer :: Buffer -> ByteString

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

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

-- | Incrementally execute builders and pass on the filled chunks as
--   bytestrings.
builderToByteString :: MonadIO m => Enumeratee Builder ByteString m a

-- | Incrementally execute builders on the given buffer and pass on the
--   filled chunks as bytestrings. Note that, if the given buffer is too
--   small for the execution of a build step, a larger one will be
--   allocated.
--   
--   WARNING: This enumeratee yields bytestrings that are NOT referentially
--   transparent. Their content will be overwritten as soon as control is
--   returned from the inner iteratee!
unsafeBuilderToByteString :: MonadIO m => IO Buffer -> Enumeratee Builder ByteString m a

-- | An enumeratee that incrementally executes builders and passes on the
--   filled chunks as bytestrings to an inner iteratee.
--   
--   INV: All bytestrings passed to the inner iteratee are non-empty.
builderToByteStringWith :: MonadIO m => BufferAllocStrategy -> Enumeratee Builder ByteString m a
