<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <!--Rendered using the Haskell Html Library v0.2--> <HTML ><HEAD ><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8" ><TITLE >Blaze.ByteString.Builder.ByteString</TITLE ><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css" ><SCRIPT SRC="haddock-util.js" TYPE="text/javascript" ></SCRIPT ><SCRIPT TYPE="text/javascript" >window.onload = function () {setSynopsis("mini_Blaze-ByteString-Builder-ByteString.html")};</SCRIPT ></HEAD ><BODY ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="topbar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" " ></TD ><TD CLASS="title" >blaze-builder-0.2.1.4: Efficient buffered output.</TD ><TD CLASS="topbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html" >Source code</A ></TD ><TD CLASS="topbut" ><A HREF="index.html" >Contents</A ></TD ><TD CLASS="topbut" ><A HREF="doc-index.html" >Index</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="modulebar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><FONT SIZE="6" >Blaze.ByteString.Builder.ByteString</FONT ></TD ><TD ALIGN="right" ><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="infohead" >Portability</TD ><TD CLASS="infoval" >tested on GHC only</TD ></TR ><TR ><TD CLASS="infohead" >Stability</TD ><TD CLASS="infoval" >experimental</TD ></TR ><TR ><TD CLASS="infohead" >Maintainer</TD ><TD CLASS="infoval" >Simon Meier <iridcode@gmail.com></TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="section4" ><B >Contents</B ></TD ></TR ><TR ><TD ><DL ><DT ><A HREF="#1" >Strict bytestrings </A ></DT ><DT ><A HREF="#2" >Lazy bytestrings </A ></DT ></DL ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Description</TD ></TR ><TR ><TD CLASS="doc" ><P ><TT ><A HREF="Blaze-ByteString-Builder-Internal-Write.html#t%3AWrite" >Write</A ></TT >s and <TT ><A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TT >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 ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Synopsis</TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="#v%3AwriteByteString" >writeByteString</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Write.html#t%3AWrite" >Write</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AfromByteString" >fromByteString</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AfromByteStringWith" >fromByteStringWith</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AcopyByteString" >copyByteString</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AinsertByteString" >insertByteString</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AfromLazyByteString" >fromLazyByteString</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AfromLazyByteStringWith" >fromLazyByteStringWith</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AcopyLazyByteString" >copyLazyByteString</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AinsertLazyByteString" >insertLazyByteString</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="1" ><A NAME="1" >Strict bytestrings </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:writeByteString" ><A NAME="v%3AwriteByteString" ></A ></A ><B >writeByteString</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Write.html#t%3AWrite" >Write</A ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#writeByteString" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Write a strict <TT ><A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A ></TT > to a buffer. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:fromByteString" ><A NAME="v%3AfromByteString" ></A ></A ><B >fromByteString</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#fromByteString" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Smart serialization of a strict bytestring. </P ><PRE ><TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AfromByteString" >fromByteString</A ></TT > = <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AfromByteStringWith" >fromByteStringWith</A ></TT > <TT ><A HREF="Blaze-ByteString-Builder-Internal.html#v%3AdefaultMaximalCopySize" >defaultMaximalCopySize</A ></TT ></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 <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AcopyByteString" >copyByteString</A ></TT > or <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AinsertByteString" >insertByteString</A ></TT > functions. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:fromByteStringWith" ><A NAME="v%3AfromByteStringWith" ></A ></A ><B >fromByteStringWith</B ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#fromByteStringWith" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="arg" >:: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A ></TD ><TD CLASS="rdoc" >Maximal number of bytes to copy. </TD ></TR ><TR ><TD CLASS="arg" >-> <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A ></TD ><TD CLASS="rdoc" >Strict <TT ><A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A ></TT > to serialize. </TD ></TR ><TR ><TD CLASS="arg" >-> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="rdoc" >Resulting <TT ><A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TT >. </TD ></TR ><TR ><TD CLASS="ndoc" COLSPAN="2" ><P ><TT >fromByteStringWith maximalCopySize bs</TT > serializes the strict bytestring <TT >bs</TT > according to the following rules. </P ><DL ><DT ><TT >S.length bs <= maximalCopySize</TT >:</DT ><DD > <TT >bs</TT > is copied to the output buffer. </DD ><DT ><TT >S.length bs > maximalCopySize</TT >:</DT ><DD > <TT >bs</TT > the output buffer is flushed and <TT >bs</TT > 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 <TT >maximalCopySize</TT >. </P ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:copyByteString" ><A NAME="v%3AcopyByteString" ></A ></A ><B >copyByteString</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#copyByteString" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P ><TT >copyByteString bs</TT > serialize the strict bytestring <TT >bs</TT > by copying it to the output buffer. </P ><P >Use this function to serialize strict bytestrings that are statically known to be smallish (<TT ><= 4kb</TT >). </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:insertByteString" ><A NAME="v%3AinsertByteString" ></A ></A ><B >insertByteString</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#insertByteString" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P ><TT >insertByteString bs</TT > serializes the strict bytestring <TT >bs</TT > 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 (<TT >> 8kb</TT >) bytestrings, as otherwise the resulting output stream may be too fragmented to be processed efficiently. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="2" ><A NAME="2" >Lazy bytestrings </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:fromLazyByteString" ><A NAME="v%3AfromLazyByteString" ></A ></A ><B >fromLazyByteString</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#fromLazyByteString" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P ><EM >O(n)</EM >. Smart serialization of a lazy bytestring. </P ><PRE ><TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AfromLazyByteString" >fromLazyByteString</A ></TT > = <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AfromLazyByteStringWith" >fromLazyByteStringWith</A ></TT > <TT ><A HREF="Blaze-ByteString-Builder-Internal.html#v%3AdefaultMaximalCopySize" >defaultMaximalCopySize</A ></TT ></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 <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AcopyLazyByteString" >copyLazyByteString</A ></TT > or <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AinsertLazyByteString" >insertLazyByteString</A ></TT > functions. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:fromLazyByteStringWith" ><A NAME="v%3AfromLazyByteStringWith" ></A ></A ><B >fromLazyByteStringWith</B ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#fromLazyByteStringWith" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="arg" >:: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A ></TD ><TD CLASS="rdoc" >Maximal number of bytes to copy. </TD ></TR ><TR ><TD CLASS="arg" >-> <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A ></TD ><TD CLASS="rdoc" >Lazy <TT ><A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A ></TT > to serialize. </TD ></TR ><TR ><TD CLASS="arg" >-> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="rdoc" >Resulting <TT ><A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TT >. </TD ></TR ><TR ><TD CLASS="ndoc" COLSPAN="2" ><P ><EM >O(n)</EM >. Serialize a lazy bytestring chunk-wise according to the same rules as in <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AfromByteStringWith" >fromByteStringWith</A ></TT >. </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 ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:copyLazyByteString" ><A NAME="v%3AcopyLazyByteString" ></A ></A ><B >copyLazyByteString</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#copyLazyByteString" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD 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 <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AcopyByteString" >copyByteString</A ></TT > for usage considerations. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:insertLazyByteString" ><A NAME="v%3AinsertLazyByteString" ></A ></A ><B >insertLazyByteString</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> <A HREF="Blaze-ByteString-Builder-Internal-Types.html#t%3ABuilder" >Builder</A ></TD ><TD CLASS="declbut" ><A HREF="src/Blaze-ByteString-Builder-ByteString.html#insertLazyByteString" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD 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 <TT ><A HREF="Blaze-ByteString-Builder-ByteString.html#v%3AinsertByteString" >insertByteString</A ></TT > for usage considerations. </P ><P >For library developers, see the ModifyChunks build signal, if you need an <EM >O(1)</EM > lazy bytestring insert based on difference lists. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="botbar" >Produced by <A HREF="http://www.haskell.org/haddock/" >Haddock</A > version 2.6.1</TD ></TR ></TABLE ></BODY ></HTML >