| Portability | tested on GHC only |
|---|---|
| Stability | experimental |
| Maintainer | Simon Meier <iridcode@gmail.com> |
| Safe Haskell | Safe-Infered |
Blaze.ByteString.Builder.ByteString
Contents
Description
- 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 -> WriteSource
Write a strict ByteString to a buffer.
fromByteString :: ByteString -> BuilderSource
Smart serialization of a strict bytestring.
fromByteString=fromByteStringWithdefaultMaximalCopySize
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.
Arguments
| :: Int | Maximal number of bytes to copy. |
| -> ByteString | Strict |
| -> Builder | Resulting |
fromByteStringWith maximalCopySize bs serializes the strict bytestring
bs according to the following rules.
S.length bs <= maximalCopySize:-
bsis copied to the output buffer. S.length bs > maximalCopySize:-
bsthe output buffer is flushed andbsis 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 -> BuilderSource
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 -> BuilderSource
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 -> BuilderSource
O(n). Smart serialization of a lazy bytestring.
fromLazyByteString=fromLazyByteStringWithdefaultMaximalCopySize
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.
Arguments
| :: Int | Maximal number of bytes to copy. |
| -> ByteString | Lazy |
| -> Builder | Resulting |
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 -> BuilderSource
O(n). Serialize a lazy bytestring by copying all chunks sequentially to the output buffer.
See copyByteString for usage considerations.
insertLazyByteString :: ByteString -> BuilderSource
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.