blaze-builder-0.4.0.1: Efficient buffered output.

Copyright | (c) 2013 Leon P Smith
License | BSD3
Maintainer | Leon P Smith <leon@melding-monads.com>
Stability | experimental
Safe Haskell | None
Language | Haskell98

Blaze.ByteString.Builder.ByteString

Contents

- Strict bytestrings
- Lazy bytestrings

Description

`Write`s and `Builder`s 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

- writeByteString :: ByteString -> Write
- fromByteString :: ByteString -> Builder
- fromByteStringWith :: Int -> ByteString -> Builder
- copyByteString :: ByteString -> Builder
- insertByteString :: ByteString -> Builder
- fromLazyByteString :: ByteString -> Builder
- fromLazyByteStringWith :: Int -> ByteString -> Builder
- copyLazyByteString :: ByteString -> Builder
- insertLazyByteString :: ByteString -> Builder

# 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 `ByteString`s 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 `ByteString`s, if it is smaller than the treshold, and inserts it directly otherwise.

For example, `fromByteStringWith 1024` copies strict `ByteString`s 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 `ByteString`s.

copyByteString :: ByteString -> Builder

Construct a `Builder` that copies the strict `ByteString`.

Use this function to create `Builder`s from smallish (`<= 4kb`) `ByteString`s 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`) `ByteString`s. 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.