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


-- | Convert streams of builders to streams of bytestrings.
--   
--   Convert streams of builders to streams of bytestrings.
@package blaze-builder-conduit
@version 1.0.0


-- | Convert a stream of blaze-builder <tt>Builder</tt>s into a stream of
--   <tt>ByteString</tt>s.
--   
--   Adapted from blaze-builder-enumerator, written by myself and Simon
--   Meier.
--   
--   Note that the functions here can work in any monad built on top of
--   <tt>IO</tt> or <tt>ST</tt>.
module Data.Conduit.Blaze

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

-- | 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 conduit yields bytestrings that are NOT referentially
--   transparent. Their content will be overwritten as soon as control is
--   returned from the inner sink!
unsafeBuilderToByteString :: MonadUnsafeIO m => IO Buffer -> Conduit Builder m ByteString

-- | A conduit that incrementally executes builders and passes on the
--   filled chunks as bytestrings to an inner sink.
--   
--   INV: All bytestrings passed to the inner sink are non-empty.
builderToByteStringWith :: MonadUnsafeIO m => BufferAllocStrategy -> Conduit Builder m ByteString

-- | Since 0.0.2
builderToByteStringFlush :: MonadUnsafeIO m => Conduit (Flush Builder) m (Flush ByteString)

-- | Since 0.0.2
builderToByteStringWithFlush :: MonadUnsafeIO m => BufferAllocStrategy -> Conduit (Flush Builder) m (Flush ByteString)

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

-- | <tt>allocBuffer size</tt> allocates a new buffer of size
--   <tt>size</tt>.
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

-- | 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
--   <a>unsafeFreezeBuffer</a> for the explanation of why this operation
--   may be unsafe.
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.
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
