Output all data written in the current buffer and start a new chunk.

The use of this function depends on how the resulting bytestrings are consumed. flush is possibly not very useful in non-interactive scenarios. However, it is kept for compatibility with the builder provided by Data.Binary.Builder.

When using toLazyByteString to extract a lazy ByteString from a Builder, this means that a new chunk will be started in the resulting lazy ByteString. The remaining part of the buffer is spilled, if the reamining free space is smaller than the minimal desired buffer size.

Extract the lazy ByteString from the builder by running it with default buffer sizes. Use this function, if you do not have any special considerations with respect to buffer sizes.

 toLazyByteString b = toLazyByteStringWith defaultBufferSize defaultMinimalBufferSize defaultFirstBufferSize b L.empty

Note that toLazyByteString is a Monoid homomorphism.

 toLazyByteString mempty          == mempty
 toLazyByteString (x `mappend` y) == toLazyByteString x `mappend` toLazyByteString y

However, in the second equation, the left-hand-side is generally faster to execute.

Run a Builder with the given buffer sizes.

Use this function for integrating the Builder type with other libraries that generate lazy bytestrings.

Note that the builders should guarantee that on average the desired chunk size is attained. Builders may decide to start a new buffer and not completely fill the existing buffer, if this is faster. However, they should not spill too much of the buffer, if they cannot compensate for it.

A call toLazyByteStringWith bufSize minBufSize firstBufSize will generate a lazy bytestring according to the following strategy. First, we allocate a buffer of size firstBufSize and start filling it. If it overflows, we allocate a buffer of size minBufSize and copy the first buffer to it in order to avoid generating a too small chunk. Finally, every next buffer will be of size bufSize. This, slow startup strategy is required to achieve good speed for short (<200 bytes) resulting bytestrings, as for them the allocation cost is of a large buffer cannot be compensated. Moreover, this strategy also allows us to avoid spilling too much memory for short resulting bytestrings.

Note that setting firstBufSize >= minBufSize implies that the first buffer is no longer copied but allocated and filled directly. Hence, setting firstBufSize = bufSize means that all chunks will use an underlying buffer of size bufSize. This is recommended, if you know that you always output more than minBufSize bytes.

Run the builder to construct a strict bytestring containing the sequence of bytes denoted by the builder. This is done by first serializing to a lazy bytestring and then packing its chunks to a appropriately sized strict bytestring.

 toByteString = packChunks . toLazyByteString

Note that toByteString is a Monoid homomorphism.

 toByteString mempty          == mempty
 toByteString (x `mappend` y) == toByteString x `mappend` toByteString y

However, in the second equation, the left-hand-side is generally faster to execute.

Run the builder with a defaultBufferSized buffer and execute the given IO action whenever the buffer is full or gets flushed.

 toByteStringIO = toByteStringIOWith defaultBufferSize

This is a Monoid homomorphism in the following sense.

 toByteStringIO io mempty          == return ()
 toByteStringIO io (x `mappend` y) == toByteStringIO io x >> toByteStringIO io y

toByteStringIOWith bufSize io b runs the builder b with a buffer of at least the size bufSize and executes the IO action io whenever the buffer is full.

Compared to toLazyByteStringWith this function requires less allocation, as the output buffer is only allocated once at the start of the serialization and whenever something bigger than the current buffer size has to be copied into the buffer, which should happen very seldomly for the default buffer size of 32kb. Hence, the pressure on the garbage collector is reduced, which can be an advantage when building long sequences of bytes.

A write of a bounded number of bytes.

When defining a function write :: a -> Write for some a, then it is important to ensure that the bound on the number of bytes written is data-independent. Formally,

 forall x y. getBound (write x) = getBound (write y)

The idea is that this data-independent bound is specified such that the compiler can optimize the check, if there are enough free bytes in the buffer, to a single subtraction between the pointer to the next free byte and the pointer to the end of the buffer with this constant bound of the maximal number of bytes to be written.

Create a builder that execute a single Write.

Construct a Builder writing a list of data one element at a time.

Write a storable value.

A builder that serializes a storable value. No alignment is done.

A builder that serializes a list of storable values by writing them consecutively. No alignment is done. Parsing information needs to be provided externally.