Blaze.ByteString.Builder.ByteString

Writes and Builders for strict and lazy bytestrings.

We assume the following qualified imports in order to differentiate between strict and lazy bytestrings in the code examples.

import qualified Data.ByteString      as S
import qualified Data.ByteString.Lazy as L

Strict bytestrings

writeByteString :: ByteString -> Write

Write a strict ByteString to a buffer.

fromByteString :: ByteString -> Builder

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

fromByteStringWith

Arguments

:: Int

Maximal number of bytes to copy.

-> ByteString

Strict ByteString to serialize.

-> Builder

Resulting Builder.

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

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

copyByteString :: ByteString -> Builder

Construct a Builder that copies the strict ByteString.

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

insertByteString :: ByteString -> Builder

Construct a Builder that always inserts the strict ByteString directly as a chunk.

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

Lazy bytestrings

fromLazyByteString :: ByteString -> Builder

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

fromLazyByteStringWith :: Int -> ByteString -> Builder

Construct a Builder that uses the thresholding strategy of fromByteStringWith for each chunk of the lazy ByteString.

copyLazyByteString :: ByteString -> Builder

Construct a Builder that copies the lazy ByteString.

insertLazyByteString :: ByteString -> Builder

Construct a Builder that inserts all chunks of the lazy ByteString directly.