A time and space-efficient implementation of lazy byte vectors using lists of packed Word8 arrays, suitable for high performance use, both in terms of large data quantities, or high speed requirements. Lazy ByteStrings are encoded as lazy lists of strict chunks of bytes.
A key feature of lazy ByteStrings is the means to manipulate large or unbounded streams of data without requiring the entire sequence to be resident in memory. To take advantage of this you have to write your functions in a lazy streaming style, e.g. classic pipeline composition. The default I/O chunk size is 32k, which should be good in most circumstances.
Some operations, such as concat, append, reverse and cons, have better complexity than their Data.ByteString equivalents, due to optimisations resulting from the list spine structure. For other operations lazy ByteStrings are usually within a few percent of strict ones.
The recomended way to assemble lazy ByteStrings from smaller parts is to use the builder monoid from Data.ByteString.Lazy.Builder.
This module is intended to be imported qualified, to avoid name clashes with Prelude functions. eg.
> import qualified Data.ByteString.Lazy as B
Original GHC implementation by Bryan O'Sullivan. Rewritten to use UArray by Simon Marlow. Rewritten to support slices and use ForeignPtr by David Roundy. Rewritten again and extended by Don Stewart and Duncan Coutts. Lazy variant by Duncan Coutts and Don Stewart.
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.
Encode each byte of a lazy ByteString using its fixed-width hex encoding.
Execute a Builder and return the generated chunks as a lazy ByteString. The work is performed lazy, i.e., only when a chunk of the lazy ByteString is forced.
Execute a Builder with custom execution parameters.
This function is forced to be inlined to allow fusing with the allocation strategy despite its rather heavy code-size. We therefore recommend that you introduce a top-level function once you have fixed your strategy. This avoids unnecessary code duplication. For example, the default Builder execution function toLazyByteString is defined as follows.
> toLazyByteString =
> toLazyByteStringWith (safeStrategy smallChunkSize defaultChunkSize) empty
In most cases, the parameters used by toLazyByteString give good performance. A sub-performing case of toLazyByteString is executing short (<128 bytes) Builders. In this case, the allocation overhead for the first 4kb buffer and the trimming cost dominate the cost of executing the Builder. You can avoid this problem using
> toLazyByteStringWith (safeStrategy 128 smallChunkSize) empty
This reduces the allocation and trimming overhead, as all generated ByteStrings fit into the first buffer and there is no trimming required, if more than 64 bytes are written.