blaze-builder-0.4.1.0: Efficient buffered output.

Copyright(c) 2013 Leon P Smith
LicenseBSD3
MaintainerLeon P Smith <leon@melding-monads.com>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell98

Blaze.ByteString.Builder.ByteString

Contents

Description

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
Synopsis

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.