 | blaze-builder-0.2.1.3: Efficient buffered output. | Contents | Index |
| Blaze.ByteString.Builder.ByteString |
|
| Contents |
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
| 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 |
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.
| :: 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.
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.
| :: 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. | |
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.