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

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

Optional configuration

data Options

Constructors

Options

Fields

initialCapacity :: !Int

trimFinalBuffer :: !Bool

runBufferBuilderWithOptions :: Options -> BufferBuilder () -> ByteString

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.