/usr/share/doc/libghc-blaze-builder-doc/html/Blaze-ByteString-Builder-ByteString.html is in libghc-blaze-builder-doc 0.3.3.2-1.
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 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | <!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>Blaze.ByteString.Builder.ByteString</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_Blaze-ByteString-Builder-ByteString.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Blaze-ByteString-Builder-ByteString.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">blaze-builder-0.3.3.2: Efficient buffered output.</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>tested on GHC only</td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Maintainer</th><td>Simon Meier <iridcode@gmail.com></td></tr><tr><th>Safe Haskell</th><td>None</td></tr></table><p class="caption">Blaze.ByteString.Builder.ByteString</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Strict bytestrings
</a></li><li><a href="#g:2">Lazy bytestrings
</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p><code><a href="Blaze-ByteString-Builder-Internal-Write.html#t:Write">Write</a></code>s and <code><a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></code>s for strict and lazy bytestrings.
</p><p>We assume the following qualified imports in order to differentiate between
strict and lazy bytestrings in the code examples.
</p><pre> import qualified Data.ByteString as S
import qualified Data.ByteString.Lazy as L
</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:writeByteString">writeByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Write.html#t:Write">Write</a></li><li class="src short"><a href="#v:fromByteString">fromByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:fromByteStringWith">fromByteStringWith</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/base-4.6.0.1/Data-Int.html#t:Int">Int</a> -> <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:copyByteString">copyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:insertByteString">insertByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:fromLazyByteString">fromLazyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:fromLazyByteStringWith">fromLazyByteStringWith</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/base-4.6.0.1/Data-Int.html#t:Int">Int</a> -> <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:copyLazyByteString">copyLazyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:insertLazyByteString">insertLazyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></li></ul></div><div id="interface"><h1 id="g:1">Strict bytestrings
</h1><div class="top"><p class="src"><a name="v:writeByteString" class="def">writeByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Write.html#t:Write">Write</a><a href="src/Blaze-ByteString-Builder-ByteString.html#writeByteString" class="link">Source</a></p><div class="doc"><p>Write a strict <code><a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code> to a buffer.
</p></div></div><div class="top"><p class="src"><a name="v:fromByteString" class="def">fromByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a><a href="src/Blaze-ByteString-Builder-ByteString.html#fromByteString" class="link">Source</a></p><div class="doc"><p>Smart serialization of a strict bytestring.
</p><pre><code><a href="Blaze-ByteString-Builder-ByteString.html#v:fromByteString">fromByteString</a></code> = <code><a href="Blaze-ByteString-Builder-ByteString.html#v:fromByteStringWith">fromByteStringWith</a></code> <code><a href="Blaze-ByteString-Builder-Internal.html#v:defaultMaximalCopySize">defaultMaximalCopySize</a></code></pre><p>Use this function to serialize strict bytestrings. It guarantees an
average chunk size of 4kb, which has been shown to be a reasonable size in
benchmarks. Note that the check whether to copy or to insert is (almost)
free as the builder performance is mostly memory-bound.
</p><p>If you statically know that copying or inserting the strict bytestring is
always the best choice, then you can use the <code><a href="Blaze-ByteString-Builder-ByteString.html#v:copyByteString">copyByteString</a></code> or
<code><a href="Blaze-ByteString-Builder-ByteString.html#v:insertByteString">insertByteString</a></code> functions.
</p></div></div><div class="top"><p class="src"><a name="v:fromByteStringWith" class="def">fromByteStringWith</a><a href="src/Blaze-ByteString-Builder-ByteString.html#fromByteStringWith" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="/usr/share/doc/ghc-doc/html/libraries/base-4.6.0.1/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>Maximal number of bytes to copy.
</p></td></tr><tr><td class="src">-> <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></td><td class="doc"><p>Strict <code><a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a></code> to serialize.
</p></td></tr><tr><td class="src">-> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></td><td class="doc"><p>Resulting <code><a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></code>.
</p></td></tr></table></div><div class="doc"><p><code>fromByteStringWith maximalCopySize bs</code> serializes the strict bytestring
<code>bs</code> according to the following rules.
</p><dl><dt><code>S.length bs <= maximalCopySize</code>:</dt><dd> <code>bs</code> is copied to the output buffer.
</dd><dt><code>S.length bs > maximalCopySize</code>:</dt><dd> <code>bs</code> the output buffer is flushed and
<code>bs</code> is inserted directly as separate chunk in the output stream.
</dd></dl><p>These rules guarantee that average chunk size in the output stream is at
least half the <code>maximalCopySize</code>.
</p></div></div><div class="top"><p class="src"><a name="v:copyByteString" class="def">copyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a><a href="src/Blaze-ByteString-Builder-ByteString.html#copyByteString" class="link">Source</a></p><div class="doc"><p><code>copyByteString bs</code> serialize the strict bytestring <code>bs</code> by copying it to
the output buffer.
</p><p>Use this function to serialize strict bytestrings that are statically known
to be smallish (<code><= 4kb</code>).
</p></div></div><div class="top"><p class="src"><a name="v:insertByteString" class="def">insertByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a><a href="src/Blaze-ByteString-Builder-ByteString.html#insertByteString" class="link">Source</a></p><div class="doc"><p><code>insertByteString bs</code> serializes the strict bytestring <code>bs</code> by inserting
it directly as a chunk of the output stream.
</p><p>Note that this implies flushing the output buffer; even if it contains just
a single byte. Hence, you should use this operation only for large (<code>> 8kb</code>)
bytestrings, as otherwise the resulting output stream may be too fragmented
to be processed efficiently.
</p></div></div><h1 id="g:2">Lazy bytestrings
</h1><div class="top"><p class="src"><a name="v:fromLazyByteString" class="def">fromLazyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a><a href="src/Blaze-ByteString-Builder-ByteString.html#fromLazyByteString" class="link">Source</a></p><div class="doc"><p><em>O(n)</em>. Smart serialization of a lazy bytestring.
</p><pre><code><a href="Blaze-ByteString-Builder-ByteString.html#v:fromLazyByteString">fromLazyByteString</a></code> = <code><a href="Blaze-ByteString-Builder-ByteString.html#v:fromLazyByteStringWith">fromLazyByteStringWith</a></code> <code><a href="Blaze-ByteString-Builder-Internal.html#v:defaultMaximalCopySize">defaultMaximalCopySize</a></code></pre><p>Use this function to serialize lazy bytestrings. It guarantees an average
chunk size of 4kb, which has been shown to be a reasonable size in
benchmarks. Note that the check whether to copy or to insert is (almost)
free as the builder performance is mostly memory-bound.
</p><p>If you statically know that copying or inserting <em>all</em> chunks of the lazy
bytestring is always the best choice, then you can use the
<code><a href="Blaze-ByteString-Builder-ByteString.html#v:copyLazyByteString">copyLazyByteString</a></code> or <code><a href="Blaze-ByteString-Builder-ByteString.html#v:insertLazyByteString">insertLazyByteString</a></code> functions.
</p></div></div><div class="top"><p class="src"><a name="v:fromLazyByteStringWith" class="def">fromLazyByteStringWith</a><a href="src/Blaze-ByteString-Builder-ByteString.html#fromLazyByteStringWith" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="/usr/share/doc/ghc-doc/html/libraries/base-4.6.0.1/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>Maximal number of bytes to copy.
</p></td></tr><tr><td class="src">-> <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></td><td class="doc"><p>Lazy <code><a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></code> to serialize.
</p></td></tr><tr><td class="src">-> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></td><td class="doc"><p>Resulting <code><a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a></code>.
</p></td></tr></table></div><div class="doc"><p><em>O(n)</em>. Serialize a lazy bytestring chunk-wise according to the same rules
as in <code><a href="Blaze-ByteString-Builder-ByteString.html#v:fromByteStringWith">fromByteStringWith</a></code>.
</p><p>Semantically, it holds that
</p><pre> fromLazyByteStringWith maxCopySize
= mconcat . map (fromByteStringWith maxCopySize) . L.toChunks
</pre><p>However, the left-hand-side is much more efficient, as it moves the
end-of-buffer pointer out of the inner loop and provides the compiler with
more strictness information.
</p></div></div><div class="top"><p class="src"><a name="v:copyLazyByteString" class="def">copyLazyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a><a href="src/Blaze-ByteString-Builder-ByteString.html#copyLazyByteString" class="link">Source</a></p><div class="doc"><p><em>O(n)</em>. Serialize a lazy bytestring by copying <em>all</em> chunks sequentially
to the output buffer.
</p><p>See <code><a href="Blaze-ByteString-Builder-ByteString.html#v:copyByteString">copyByteString</a></code> for usage considerations.
</p></div></div><div class="top"><p class="src"><a name="v:insertLazyByteString" class="def">insertLazyByteString</a> :: <a href="/usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.0.2/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="Blaze-ByteString-Builder-Internal-Types.html#t:Builder">Builder</a><a href="src/Blaze-ByteString-Builder-ByteString.html#insertLazyByteString" class="link">Source</a></p><div class="doc"><p><em>O(n)</em>. Serialize a lazy bytestring by inserting <em>all</em> its chunks directly
into the output stream.
</p><p>See <code><a href="Blaze-ByteString-Builder-ByteString.html#v:insertByteString">insertByteString</a></code> for usage considerations.
</p><p>For library developers, see the <code>ModifyChunks</code> build signal, if you
need an <em>O(1)</em> lazy bytestring insert based on difference lists.
</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>
|