/usr/share/doc/libghc-io-streams-doc/html/System-IO-Streams-Builder.html is in libghc-io-streams-doc 1.3.5.0-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 | <!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 src="file:///usr/share/javascript/mathjax/MathJax.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.3.5.0: 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><tr><th>Language</th><td>Haskell2010</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>bytestring</code>
package provides an efficient monoidal datatype used for serializing values
directly to an output buffer, called a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a></code>, originally implemented in
the <code>blaze-builder</code> package by Simon Meier. When compiling with <code>bytestring</code>
versions older than 0.10.4, (i.e. GHC <= 7.6) users must depend on the
<code>bytestring-builder</code> library to get the new builder implementation. Since we
try to maintain compatibility with the last three GHC versions, the
dependency on <code>bytestring-builder</code> can be dropped after the release of GHC
7.12.</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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/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="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.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="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Maybe.html#v:Just">Just</a></code> $ <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder.html#v:byteString">byteString</a></code> "hello") newStream
....
</pre><p>You can flush the output buffer using <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder-Extra.html#v:flush">flush</a></code>:</p><pre> ....
Streams.<code><a href="System-IO-Streams-Internal.html#v:write">write</a></code> (<code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Maybe.html#v:Just">Just</a></code> <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder-Extra.html#v: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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/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 <code>handleToOutputStream</code> and
<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="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-List.html#v:intersperse">intersperse</a></code> " " ["the", "quick", "brown", "fox"]
let l2 = <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-List.html#v:intersperse">intersperse</a></code> " " ["jumped", "over", "the"]
let l = map <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder.html#v:byteString">byteString</a></code> l1 ++ [<code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder-Extra.html#v:flush">flush</a></code>] ++ map <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder.html#v:byteString">byteString</a></code> l2
is <- Streams.<code><a href="System-IO-Streams.html#v:fromList">fromList</a></code> l
(os0, grab) <- Streams.<code><a href="System-IO-Streams.html#v: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#v: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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a>)</li><li class="src short"><a href="#v:builderStreamWithBufferSize">builderStreamWithBufferSize</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a> -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a>)</li><li class="src short"><a href="#v:unsafeBuilderStream">unsafeBuilderStream</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> Buffer -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.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 id="v:builderStream" class="def">builderStream</a> :: <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a>) <a href="src/System-IO-Streams-Builder.html#builderStream" class="link">Source</a> <a href="#v:builderStream" class="selflink">#</a></p><div class="doc"><p>Converts a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> sink into a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a></code> sink.</p><p>Note that if the generated builder receives a
<code><a href="Blaze-ByteString-Builder.html#v: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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/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 id="v:builderStreamWithBufferSize" class="def">builderStreamWithBufferSize</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a> -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a>) <a href="src/System-IO-Streams-Builder.html#builderStreamWithBufferSize" class="link">Source</a> <a href="#v:builderStreamWithBufferSize" class="selflink">#</a></p><div class="doc"><p>Converts a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> sink into a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a></code> sink, using the supplied
buffer size.</p><p>Note that if the generated builder receives a
<code><a href="Blaze-ByteString-Builder.html#v: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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code></code> to indicate that any output
buffers are to be flushed.</p><p><em>Since: 1.3.0.0.</em></p></div></div><div class="top"><p class="src"><a id="v:unsafeBuilderStream" class="def">unsafeBuilderStream</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> Buffer -> <a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="System-IO-Streams-Internal.html#t:OutputStream">OutputStream</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a>) <a href="src/System-IO-Streams-Builder.html#unsafeBuilderStream" class="link">Source</a> <a href="#v:unsafeBuilderStream" class="selflink">#</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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/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="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#v: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>newBuffer</code>.</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.17.2</p></div></body></html>
|