blaze-builder-0.3.1.1: Efficient buffered output.

Portability | tested on GHC only
Stability | experimental
Maintainer | Simon Meier <iridcode@gmail.com>
Safe Haskell | None

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

Smart serialization of a strict bytestring.

    fromByteString = fromByteStringWith defaultMaximalCopySize

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.

If you statically know that copying or inserting the strict bytestring is always the best choice, then you can use the `copyByteString` or `insertByteString` functions.

fromByteStringWith

Arguments

:: Int | Maximal number of bytes to copy.
-> ByteString | Strict `ByteString` to serialize.
-> Builder | Resulting `Builder`.

`fromByteStringWith maximalCopySize bs` serializes the strict bytestring `bs` according to the following rules.

`S.length bs <= maximalCopySize`:
  `bs` is copied to the output buffer.
`S.length bs > maximalCopySize`:
  `bs` the output buffer is flushed and `bs` is inserted directly as separate chunk in the output stream.

These rules guarantee that average chunk size in the output stream is at least half the `maximalCopySize`.

copyByteString :: ByteString -> Builder

`copyByteString bs` serialize the strict bytestring `bs` by copying it to the output buffer.

Use this function to serialize strict bytestrings that are statically known to be smallish (`<= 4kb`).

insertByteString :: ByteString -> Builder

`insertByteString bs` serializes the strict bytestring `bs` by inserting it directly as a chunk of the output stream.

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 (`> 8kb`) bytestrings, as otherwise the resulting output stream may be too fragmented to be processed efficiently.

# Lazy bytestrings

fromLazyByteString :: ByteString -> Builder

O(n). Smart serialization of a lazy bytestring.

    fromLazyByteString = fromLazyByteStringWith defaultMaximalCopySize

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.

If you statically know that copying or inserting all chunks of the lazy bytestring is always the best choice, then you can use the `copyLazyByteString` or `insertLazyByteString` functions.

fromLazyByteStringWith

Arguments

:: Int | Maximal number of bytes to copy.
-> ByteString | Lazy `ByteString` to serialize.
-> Builder | Resulting `Builder`.

O(n). Serialize a lazy bytestring chunk-wise according to the same rules as in `fromByteStringWith`.

Semantically, it holds that

       fromLazyByteStringWith maxCopySize
     = mconcat . map (fromByteStringWith maxCopySize) . L.toChunks

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.

copyLazyByteString :: ByteString -> Builder

O(n). Serialize a lazy bytestring by copying all chunks sequentially to the output buffer.

See `copyByteString` for usage considerations.

insertLazyByteString :: ByteString -> Builder

O(n). Serialize a lazy bytestring by inserting all its chunks directly into the output stream.

See `insertByteString` for usage considerations.

For library developers, see the `ModifyChunks` build signal, if you need an O(1) lazy bytestring insert based on difference lists.