Data.BufferBuilder

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

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.

Instances

Monad BufferBuilder

Functor BufferBuilder

Applicative BufferBuilder

runBufferBuilder :: BufferBuilder a -> ByteString

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

runBufferBuilder' :: BufferBuilder a -> (a, ByteString)

Run a sequence of BufferBuilder actions and extract the resulting buffer as a ByteString. Also returns the BufferBuilder's result.

Optional configuration

data Options

Constructors

Options

Fields

initialCapacity :: !Int

trimFinalBuffer :: !Bool

runBufferBuilderWithOptions :: Options -> BufferBuilder a -> ByteString

runBufferBuilderWithOptions' :: Options -> BufferBuilder a -> (a, ByteString)

Query builder

calculateLength :: BufferBuilder a -> Int

Given a BufferBuilder, calculate its length. This runs every BufferBuilder action in a mode that simply accumulates the number of bytes without copying any data into an output buffer.

currentLength :: BufferBuilder Int

Reads current length of BufferBuilder. If memory allocation has failed at any point, this returns zero. In the future, currentLength may throw an exception upon memory allocation failure.

Appending bytes and byte strings

appendByte :: Word8 -> BufferBuilder ()

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 ()

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

appendBS :: ByteString -> BufferBuilder ()

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 ()

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

appendLiteral :: Addr# -> BufferBuilder ()

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 ()

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

appendByte7 :: Word8 -> BufferBuilder ()

appendChar7 :: Char -> BufferBuilder ()

appendBS7 :: ByteString -> BufferBuilder ()

appendLiteral7 :: Addr# -> BufferBuilder ()

unsafeAppendLiteralN7 :: Int -> Addr# -> BufferBuilder ()

UTF-8 encoding

appendCharUtf8 :: Char -> BufferBuilder ()

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

appendStringUtf8 :: String -> BufferBuilder ()

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 ()

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

appendDecimalDouble :: Double -> BufferBuilder ()

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

JSON escaping

appendEscapedJson :: ByteString -> BufferBuilder ()

appendEscapedJsonLiteral :: Addr# -> BufferBuilder ()

appendEscapedJsonText :: Text -> BufferBuilder ()

URL percent-encoding

appendUrlEncoded :: ByteString -> BufferBuilder ()

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.