Documentation

Writes bytes in reverse order, updating the current state.

It is the responsibility of the execution context and buffer management primitives to ensure that the current buffer remains reachable during builder execution, though completed buffers may be copied to new storage at any time. Aside from those primitives, BuildR implementations may ignore that issue.

When combining BuildRs with <> we expect the best performance when associating to the left. For example foldl (<>) mempty, though unless your foldl iteration starts from the right there may still be issues. Consider using vectorBuildR instead of foldMap.

The current state of execution of a builder is a StablePtr (IORef BuildRState).

Current Buffer Layout:

We devote the first few octets of the current buffer to metadata that does not change very frequently:

• Addr#: cast to 'StablePtr# (IORef BuildRState)'; indirect acceses to the full builder state, which is used relatively infrequently.
• Int#: the total number of non-metadata bytes originally available within the current buffer before we started consuming them,
• plus* the number of bytes actually written to previous buffers. We subtract the current unused figure to get the total bytes written.
• Double#: suitably-aligned scratch space for serialization of Double and Float values.

Though this choice imposes a small memory overhead in every buffer, it reduces the time and space required to save and restore metadata around the many non-inline calls that typically occur while writing data into the buffer.

Needed for rewrite rules; normally you would use <>.

Like foldl but iterates right-to-left, which is often useful when creating reverse builders.

Eta-expands a function that produces a BuildR, so that its input is not evaluated until the builder state is presented.

This odd combinator seems to help performance at times, though it may change behavior on nonterminating values of type a.

Like toLazyByteString but also returns the total length of the lazy ByteString, which is computed as a side effect of encoding.

The result of a call to sealBuffer.

Takes ownership of the current buffer, but sometimes hands it back for reuse.

If more building is required then please allocate a new current buffer and update the builder state variable accordingly.

(This is a manual wrapper around sealBuffer#.)

First reads the number of unused bytes in the current buffer.

First reads the number of bytes previously written.

The arguments are the same as the BuildR arguments.

Executes the right builder, measuring how many bytes it writes, then provides that figure to the left builder.

Executes the right builder, measuring how many bytes it writes, then provides that figure to the left builder.

Seals the current buffer and creates a new one with at least the given number of bytes.

Prepends a ByteString to the output.

NOTE: This is a relatively heavyweight operation. For small strings it may be faster to copy them to the current buffer.

Like ByteString, but with the chunks in reverse order, even though the bytes within each chunk are in forward order.

Equivalent to the following, but faster:

foldMap prependChunk . reverse . getReverseChunks

NOTE: This is a relatively heavyweight operation. For small strings it may be faster to copy them to the current buffer.

Ensures that the current buffer has at least the given number of bytes before executing the given builder.

ASSUMES that the specified number of bytes is both nonnegative and less than or equal to the number of unused bytes in the current buffer, consumes that number of unused bytes, and provides their starting address.

Given the builder inputs and a Float, converts that number to its bit pattern in native byte order.

Given the builder inputs and a Double, converts that number to its bit pattern in native byte order.