buffer-builder- Library for efficiently building up buffers, one piece at a time

Safe HaskellNone




A library for efficiently building up a buffer of data. When given data known to be strict, use of BufferBuilder compiles directly into a series of efficient C function calls.


The BufferBuilder Monad

data BufferBuilder a Source

BufferBuilder is the type of a monadic action that appends to an implicit, growable buffer. Use runBufferBuilder to extract the resulting buffer as a ByteString.

runBufferBuilder :: BufferBuilder () -> ByteString Source

Run a sequence of BufferBuilder actions and extract the resulting buffer as a ByteString.

Optional configuration

data Options Source



Appending bytes and byte strings

appendByte :: Word8 -> BufferBuilder () Source

Append a single byte to the output buffer. To append multiple bytes in sequence and avoid redundant bounds checks, consider using appendBS, appendLiteral, or unsafeAppendLiteralN.

appendChar8 :: Char -> BufferBuilder () Source

Appends a character to the buffer, truncating it to the bottom 8 bits.

appendBS :: ByteString -> BufferBuilder () Source

Appends a ByteString to the buffer. When appending constant, hardcoded strings, to avoid a CAF and the costs of its associated tag check and indirect jump, use appendLiteral or unsafeAppendLiteralN instead.

appendLBS :: ByteString -> BufferBuilder () Source

Appends a lazy ByteString to the buffer. This function operates by traversing the lazy ByteString chunks, appending each in turn.

appendLiteral :: Addr# -> BufferBuilder () Source

Appends a zero-terminated MagicHash string literal. Use this function instead of appendBS for string constants. For example:

appendLiteral "true"#

If the length of the string literal is known, calling unsafeAppendLiteralN is faster, as unsafeAppendLiteralN avoids a strlen operation which has nontrivial cost in some benchmarks.

unsafeAppendLiteralN :: Int -> Addr# -> BufferBuilder () Source

Appends a MagicHash string literal with a known length. Use this when the string literal's length is known. For example:

unsafeAppendLiteralN 4 "true"#

Per byte, this is the fastest append function. It amounts to a C function call with two constant arguments. The C function checks to see if it needs to grow the buffer and then it simply calls memcpy.

WARNING: passing an incorrect length value is likely to cause an access violation or worse.

Appending bytes and byte strings, truncated to 7 bits

UTF-8 encoding

appendCharUtf8 :: Char -> BufferBuilder () Source

Appends a UTF-8-encoded Char to the buffer.

appendStringUtf8 :: String -> BufferBuilder () Source

Appends a UTF-8-encoded String to the buffer. The best way to improve performance here is to use ByteString or Text instead of String.

Printing numbers

appendDecimalSignedInt :: Int -> BufferBuilder () Source

Appends a decimal integer, just like calling printf("%d", ...)

appendDecimalDouble :: Double -> BufferBuilder () Source

Appends a decimal double, just like calling printf("%f", ...)

JSON escaping

URL percent-encoding

appendUrlEncoded :: ByteString -> BufferBuilder () Source

Append a percent-encoded ByteString. All characters except for alphanumerics, -, ., _, and ~ will be encoded. The string produced by URL encoding is guaranteed ASCII-7 and thus valid UTF-8. Moreover, it is not required to be JSON-escaped.