libghc-blaze-builder-doc 0.4.0.1-3build1 / usr / share / doc / libghc-blaze-builder-doc / html / blaze-builder.txt

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


-- | Efficient buffered output.
--   
--   This library provides an implementation of the older blaze-builder
--   interface in terms of the new builder that shipped with
--   bytestring-0.10.4.0
--   
--   This implementation is mostly intended as a bridge to the new builder,
--   so that code that uses the old interface can interoperate with code
--   that uses the new implementation. Note that no attempt has been made
--   to preserve the old internal modules, so code that has these
--   dependencies cannot use this interface.
--   
--   New code should, for the most part, use the new interface. However,
--   this module does implement a chunked HTTP encoding, which is not
--   otherwise implemented (yet?) with the new builder.
@package blaze-builder
@version 0.4.0.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.
--   <a>Poke</a>s are the most primitive buffer manipulation. In most
--   cases, you don't use the explicitely but as part of a <a>Write</a>,
--   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)

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

-- | A write of a bounded number of bytes.
--   
--   When defining a function <tt>write :: a -&gt; Write</tt> for some
--   <tt>a</tt>, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   <pre>
--   forall x y. getBound (write x) = getBound (write y)
--   </pre>
--   
--   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 <a>Poke</a> 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 <a>Poke</a> action of a write.
getPoke :: Write -> Poke

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

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

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

-- | <tt>writeIf p wTrue wFalse x</tt> creates a <a>Write</a> with a
--   <a>Poke</a> equal to <tt>wTrue x</tt>, if <tt>p x</tt> and equal to
--   <tt>wFalse x</tt> otherwise. The bound of this new <a>Write</a> is the
--   maximum of the bounds for either <a>Write</a>. This yields a data
--   independent bound, if the bound for <tt>wTrue</tt> and <tt>wFalse</tt>
--   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 <a>Write</a>.
fromWrite :: Write -> Builder
fromWriteSingleton :: (a -> Write) -> (a -> Builder)

-- | Construct a <a>Builder</a> 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.Base.Monoid Blaze.ByteString.Builder.Internal.Write.Poke
instance GHC.Base.Monoid 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 <tt>write :: a -&gt; Write</tt> for some
--   <tt>a</tt>, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   <pre>
--   forall x y. getBound (write x) = getBound (write y)
--   </pre>
--   
--   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


-- | <a>Write</a>s and <a>Builder</a>s 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

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

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

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

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

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


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

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

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

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

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

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

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


-- | <a>Write</a>s and <tt>Builder</tt>s 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 <tt>Builder</tt> from 'blaze-builder'
--   replaces the <a>Builder</a> 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

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

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

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

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

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


-- | <a>Write</a>s and <a>Builder</a>s for strict and lazy bytestrings.
--   
--   We assume the following qualified imports in order to differentiate
--   between strict and lazy bytestrings in the code examples.
--   
--   <pre>
--   import qualified Data.ByteString      as S
--   import qualified Data.ByteString.Lazy as L
--   </pre>
module Blaze.ByteString.Builder.ByteString

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

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

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

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

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

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

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

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

-- | Construct a <a>Builder</a> that inserts all chunks of the lazy
--   <a>ByteString</a> 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 '0\r\n\r\n' signaling the termination of the
--   data transfer.
chunkedTransferTerminator :: Builder


-- | <a>Write</a>s and <a>Builder</a>s for serializing words.
--   
--   Note that for serializing a three tuple <tt>(x,y,z)</tt> of bytes (or
--   other word values) you should use the expression
--   
--   <pre>
--   fromWrite $ writeWord8 x `mappend` writeWord8 y `mappend` writeWord z
--   </pre>
--   
--   instead of
--   
--   <pre>
--   fromWord8 x `mappend` fromWord8 y `mappend` fromWord z
--   </pre>
--   
--   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 <a>Word16</a> in big endian format.
writeWord16be :: Word16 -> Write

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

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

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

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

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

-- | Write a single native machine <a>Word</a>. The <a>Word</a> is written
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the <a>Word</a> 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 <a>Word16</a> in native host order and host endianness.
writeWord16host :: Word16 -> Write

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

-- | Write a <a>Word64</a> 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 <a>Word16</a> in big endian format.
fromWord16be :: Word16 -> Builder

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

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

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

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

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

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

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

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

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

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

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

-- | Serialize a single native machine <a>Word</a>. The <a>Word</a> is
--   serialized in host order, host endian form, for the machine you're on.
--   On a 64 bit machine the <a>Word</a> 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 <a>Word16</a> in native host order and host endianness.
fromWord16host :: Word16 -> Builder

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

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

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

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

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

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


-- | <a>Write</a>s and <a>Builder</a>s for serializing integers.
--   
--   See <a>Blaze.ByteString.Builder.Word</a> 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 <a>Int16</a> in big endian format.
writeInt16be :: Int16 -> Write

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

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

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

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

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

-- | Write a single native machine <a>Int</a>. The <a>Int</a> is written in
--   host order, host endian form, for the machine you're on. On a 64 bit
--   machine the <a>Int</a> 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 <a>Int16</a> in native host order and host endianness.
writeInt16host :: Int16 -> Write

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

-- | Write an <a>Int64</a> 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 <a>Int16</a> in big endian format.
fromInt16be :: Int16 -> Builder

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

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

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

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

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

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

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

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

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

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

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

-- | Serialize a single native machine <a>Int</a>. The <a>Int</a> is
--   serialized in host order, host endian form, for the machine you're on.
--   On a 64 bit machine the <a>Int</a> 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 <a>Int16</a> in native host order and host endianness.
fromInt16host :: Int16 -> Builder

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

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

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

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

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

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


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

-- | <a>Builder</a>s denote sequences of bytes. They are <a>Monoid</a>s
--   where <a>mempty</a> is the zero-length sequence and <a>mappend</a> is
--   concatenation, which runs in <i>O(1)</i>.
data Builder :: *

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

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

-- | Run a <a>Builder</a> with the given buffer sizes.
--   
--   Use this function for integrating the <a>Builder</a> 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 <tt>toLazyByteStringWith bufSize minBufSize firstBufSize</tt>
--   will generate a lazy bytestring according to the following strategy.
--   First, we allocate a buffer of size <tt>firstBufSize</tt> and start
--   filling it. If it overflows, we allocate a buffer of size
--   <tt>minBufSize</tt> and copy the first buffer to it in order to avoid
--   generating a too small chunk. Finally, every next buffer will be of
--   size <tt>bufSize</tt>. This, slow startup strategy is required to
--   achieve good speed for short (&lt;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 <tt>firstBufSize &gt;= minBufSize</tt> implies that
--   the first buffer is no longer copied but allocated and filled
--   directly. Hence, setting <tt>firstBufSize = bufSize</tt> means that
--   all chunks will use an underlying buffer of size <tt>bufSize</tt>.
--   This is recommended, if you know that you always output more than
--   <tt>minBufSize</tt> 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.
--   
--   <pre>
--   toByteString = packChunks . toLazyByteString
--   </pre>
--   
--   Note that <tt><a>toByteString</a></tt> is a <a>Monoid</a>
--   homomorphism.
--   
--   <pre>
--   toByteString mempty          == mempty
--   toByteString (x `mappend` y) == toByteString x `mappend` toByteString y
--   </pre>
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toByteString :: Builder -> ByteString

-- | <tt>toByteStringIOWith bufSize io b</tt> runs the builder <tt>b</tt>
--   with a buffer of at least the size <tt>bufSize</tt> and executes the
--   <a>IO</a> action <tt>io</tt> whenever the buffer is full.
--   
--   Compared to <a>toLazyByteStringWith</a> 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 <tt>write :: a -&gt; Write</tt> for some
--   <tt>a</tt>, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   <pre>
--   forall x y. getBound (write x) = getBound (write y)
--   </pre>
--   
--   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 <a>Write</a>.
fromWrite :: Write -> Builder
fromWriteSingleton :: (a -> Write) -> (a -> Builder)

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

-- | Run a <tt>Write</tt> to produce a strict <a>ByteString</a>. This is
--   equivalent to <tt>(<a>toByteString</a> . <tt>fromWrite</tt>)</tt>, 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