<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>System.IO.Streams.Builder</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_System-IO-Streams-Builder.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/System-IO-Streams-Builder.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">io-streams-1.1.4.5: Simple, composable, and easy-to-use stream I/O</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Safe Haskell</th><td>None</td></tr></table><p class="caption">System.IO.Streams.Builder</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Blaze builder conversion
</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Buffering for output streams based on bytestring builders.
</p><p>Buffering an output stream can often improve throughput by reducing the
number of system calls made through the file descriptor. The <code>blaze-builder</code>
package provides an efficient set of primitives for serializing values
directly to an output buffer.
</p><p>(<em>N.B.</em>: most of the <code>blaze-builder</code> package has been moved into
<code>bytestring</code> in versions >= 0.10; once two or three Haskell Platform
editions have been released that contain <code>bytestring</code> 0.10 or higher, the
dependency on <code>blaze-builder</code> will be dropped in favor of the native support
for <code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></code> contained in the <code>bytestring</code> package.)
</p><p><em>Using this module</em>
</p><p>Given an <code><a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a></code> taking <code><a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code>:
</p><pre> someOutputStream :: OutputStream ByteString
</pre><p>You create a new output stream wrapping the original one that accepts
<code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></code> values:
</p><pre>
do
newStream <- Streams.<code><a href="System-IO-Streams-Builder.html#v:builderStream">builderStream</a></code> someOutputStream
Streams.<code><a href="System-IO-Streams-Internal.html#v:write">write</a></code> (<code><a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/Data-Maybe.html#v:Just">Just</a></code> $ <code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder.html#t:fromByteString">fromByteString</a></code> "hello") newStream
....
</pre><p>You can flush the output buffer using <code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder.html#t:flush">flush</a></code>:
</p><pre>
....
Streams.<code><a href="System-IO-Streams-Internal.html#v:write">write</a></code> (<code><a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/Data-Maybe.html#v:Just">Just</a></code> <code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder.html#t:flush">flush</a></code>) newStream
....
</pre><p>As a convention, <code><a href="System-IO-Streams-Builder.html#v:builderStream">builderStream</a></code> will write the empty string to the wrapped
<code><a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a></code> upon a builder buffer flush. Output streams which receive
<code><a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code> should either ignore the empty string or interpret it as a
signal to flush their own buffers, as the <a href="System-IO-Streams-Zlib.html">System.IO.Streams.Zlib</a> functions
do.
</p><p><em>Example</em>
</p><pre>
example :: IO [ByteString]
example = do
let l1 = <code><a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/Data-List.html#t:intersperse">intersperse</a></code> " " ["the", "quick", "brown", "fox"]
let l2 = <code><a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/Data-List.html#t:intersperse">intersperse</a></code> " " ["jumped", "over", "the"]
let l = map <code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder.html#t:fromByteString">fromByteString</a></code> l1 ++ [<code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder.html#t:flush">flush</a></code>] ++ map <code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder.html#t:fromByteString">fromByteString</a></code> l2
is <- Streams.<code><a href="System-IO-Streams.html#t:fromList">fromList</a></code> l
(os0, grab) <- Streams.<code><a href="System-IO-Streams.html#t:listOutputStream">listOutputStream</a></code>
os <- Streams.<code><a href="System-IO-Streams-Builder.html#v:builderStream">builderStream</a></code> os0
Streams.<code><a href="System-IO-Streams.html#t:connect">connect</a></code> is os >> grab
ghci> example
["the quick brown fox","","jumped over the"]
</pre></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:builderStream">builderStream</a> :: <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a>)</li><li class="src short"><a href="#v:unsafeBuilderStream">unsafeBuilderStream</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Buffer.html#t:Buffer">Buffer</a> -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a>)</li><li class="src short"><a href="#v:builderStreamWith">builderStreamWith</a> :: <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Buffer.html#t:BufferAllocStrategy">BufferAllocStrategy</a> -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a>)</li></ul></div><div id="interface"><h1 id="g:1">Blaze builder conversion
</h1><div class="top"><p class="src"><a name="v:builderStream" class="def">builderStream</a> :: <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a>)<a href="src/System-IO-Streams-Builder.html#builderStream" class="link">Source</a></p><div class="doc"><p>Converts a <code><a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code> sink into a <code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></code> sink.
</p><p>Note that if the generated builder receives a
<code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder.html#t:flush">flush</a></code>, by convention it will send an empty string
to the supplied <code><code><a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a></code> <code><a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code></code> to indicate that any output
buffers are to be flushed.
</p></div></div><div class="top"><p class="src"><a name="v:unsafeBuilderStream" class="def">unsafeBuilderStream</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Buffer.html#t:Buffer">Buffer</a> -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a>)<a href="src/System-IO-Streams-Builder.html#unsafeBuilderStream" class="link">Source</a></p><div class="doc"><p>Unsafe variation on <code><a href="System-IO-Streams-Builder.html#v:builderStream">builderStream</a></code> that reuses an existing buffer for
efficiency.
</p><p><em>NOTE</em>: because the buffer is reused, subsequent <code><a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code> values written
to the wrapped <code>OutputString</code> will cause previous yielded strings to change.
Do not retain references to these <code><a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code> values inside the
<code><a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a></code> you pass to this function, or you will violate referential
transparency.
</p><p>If you <em>must</em> retain copies of these values, then please use
<code><a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:copy">copy</a></code> to ensure that you have a fresh copy of the
underlying string.
</p><p>You can create a Buffer with
<code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Buffer.html#t:allocBuffer">allocBuffer</a></code>.
</p></div></div><div class="top"><p class="src"><a name="v:builderStreamWith" class="def">builderStreamWith</a> :: <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Buffer.html#t:BufferAllocStrategy">BufferAllocStrategy</a> -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="/usr/share/doc/ghc/html/libraries/base-4.6.0.1/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a>)<a href="src/System-IO-Streams-Builder.html#builderStreamWith" class="link">Source</a></p><div class="doc"><p>A customized version of <code><a href="System-IO-Streams-Builder.html#v:builderStream">builderStream</a></code>, using the specified
<code><a href="/usr/share/doc/ghc/html/libraries/blaze-builder-0.3.1.1/Blaze-ByteString-Builder-Internal-Buffer.html#t:BufferAllocStrategy">BufferAllocStrategy</a></code>.
</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.13.2</p></div></body></html>
