Write a strict ByteString to a buffer.

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 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 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 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.

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.

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.

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

See copyByteString for usage considerations.

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.