Data.ByteString.Builder.Internal

The Builder denoting a zero-length sequence of bytes. This function is only exported for use in rewriting rules. Use mempty otherwise.

Concatenate two Builders. This function is only exported for use in rewriting rules. Use mappend otherwise.

Flush the current buffer. This introduces a chunk boundary.

ensureFree n ensures that there are at least n free bytes for the following Builder.

Construct a Builder that copies the StrictByteString.

Use this function to create Builders from smallish (<= 4kb) StrictByteStrings or if you need to guarantee that the StrictByteString is not shared with the chunks generated by the Builder.

Construct a Builder that always inserts the StrictByteString directly as a chunk.

This implies flushing the output buffer, even if it contains just a single byte. You should therefore use byteStringInsert only for large (> 8kb) StrictByteStrings. Otherwise, the generated chunks are too fragmented to be processed efficiently afterwards.

Construct a Builder that copies the StrictByteStrings, if it is smaller than the treshold, and inserts it directly otherwise.

For example, byteStringThreshold 1024 copies StrictByteStrings whose size is less or equal to 1kb, and inserts them directly otherwise. This implies that the average chunk-size of the generated LazyByteString may be as low as 513 bytes, as there could always be just a single byte between the directly inserted 1025 byte, StrictByteStrings.

Construct a Builder that copies the LazyByteString.

Construct a Builder that inserts all chunks of the LazyByteString directly.

Construct a Builder that uses the thresholding strategy of byteStringThreshold for each chunk of the LazyByteString.

Construct a Builder that copies the SH.ShortByteString.

The maximal size of a StrictByteString that is copied. 2 * smallChunkSize to guarantee that on average a chunk is of smallChunkSize.

Create a Builder denoting the same sequence of bytes as a StrictByteString. The Builder inserts large StrictByteStrings directly, but copies small ones to ensure that the generated chunks are large on average.

Create a Builder denoting the same sequence of bytes as a lazy LazyByteString. The Builder inserts large chunks of the LazyByteString directly, but copies small ones to ensure that the generated chunks are large on average.

Execute a Builder and return the generated chunks as a LazyByteString. The work is performed lazy, i.e., only when a chunk of the LazyByteString is forced.

Heavy inlining. Execute a Builder with custom execution parameters.

This function is inlined despite its heavy code-size to allow fusing with the allocation strategy. For example, the default Builder execution function toLazyByteString is defined as follows.

{-# NOINLINE toLazyByteString #-}
toLazyByteString =
  toLazyByteStringWith (safeStrategy smallChunkSize defaultChunkSize) L.Empty

where L.Empty is the zero-length LazyByteString.

In most cases, the parameters used by toLazyByteString give good performance. A sub-performing case of toLazyByteString is executing short (<128 bytes) Builders. In this case, the allocation overhead for the first 4kb buffer and the trimming cost dominate the cost of executing the Builder. You can avoid this problem using

toLazyByteStringWith (safeStrategy 128 smallChunkSize) L.Empty

This reduces the allocation and trimming overhead, as all generated LazyByteStrings fit into the first buffer and there is no trimming required, if more than 64 bytes and less than 128 bytes are written.

A buffer allocation strategy for executing Builders.

Use this strategy for generating LazyByteStrings whose chunks are likely to survive one garbage collection. This strategy trims buffers that are filled less than half in order to avoid spilling too much memory.

Use this strategy for generating LazyByteStrings whose chunks are discarded right after they are generated. For example, if you just generate them to write them to a network socket.

Create a custom allocation strategy. See the code for safeStrategy and untrimmedStrategy for examples.

The recommended chunk size. Currently set to 4k, less the memory management overhead

The chunk size used for I/O. Currently set to 32k, less the memory management overhead

The memory management overhead. Currently this is tuned for GHC only.

Execute a Put and return the computed result and the bytes written during the computation as a LazyByteString.

This function is strict in the computed result and lazy in the writing of the bytes. For example, given

infinitePut = sequence_ (repeat (putBuilder (word8 1))) >> return 0
 

evaluating the expression

fst $ putToLazyByteString infinitePut
 

does not terminate, while evaluating the expression

L.head $ snd $ putToLazyByteString infinitePut
 

does terminate and yields the value 1 :: Word8.

An illustrative example for these strictness properties is the implementation of Base64 decoding (http://en.wikipedia.org/wiki/Base64).

type DecodingState = ...

decodeBase64 :: StrictByteString -> DecodingState -> Put (Maybe DecodingState)
decodeBase64 = ...
 

The above function takes a StrictByteString supposed to represent Base64 encoded data and the current decoding state. It writes the decoded bytes as the side-effect of the Put and returns the new decoding state, if the decoding of all data in the StrictByteString was successful. The checking if the StrictByteString represents Base64 encoded data and the actual decoding are fused. This makes the common case, where all data represents Base64 encoded data, more efficient. It also implies that all data must be decoded before the final decoding state can be returned. Puts are intended for implementing such fused checking and decoding/encoding, which is reflected in their strictness properties.

Execute a Put with a buffer-allocation strategy and a continuation. For example, putToLazyByteString is implemented as follows.

putToLazyByteString = putToLazyByteStringWith
    (safeStrategy smallChunkSize defaultChunkSize) (x -> (x, L.empty))
 

Run a Put action redirecting the produced output to a Handle.

The output is buffered using the Handles associated buffer. If this buffer is too small to execute one step of the Put action, then it is replaced with a large enough buffer.

Run a Builder as a side-effect of a Put () action.

Convert a Put () action to a Builder.