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

Safe HaskellNone
LanguageHaskell2010

Data.BufferBuilder

Contents

Description

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.

Synopsis

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.

Instances
Monad BufferBuilder Source # 
Instance details

Defined in Data.BufferBuilder

Functor BufferBuilder Source # 
Instance details

Defined in Data.BufferBuilder

Methods

fmap :: (a -> b) -> BufferBuilder a -> BufferBuilder b #

(<$) :: a -> BufferBuilder b -> BufferBuilder a #

Applicative BufferBuilder Source # 
Instance details

Defined in Data.BufferBuilder

runBufferBuilder :: BufferBuilder a -> ByteString Source #

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

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

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

Optional configuration

data Options Source #

Constructors

Options 

Query builder

calculateLength :: BufferBuilder a -> Int Source #

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 Source #

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