buffer-builder

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

https://github.com/chadaustin/buffer-builder

Version on this page:0.2.4.4
LTS Haskell 22.13:0.2.4.8
Stackage Nightly 2023-12-26:0.2.4.8
Latest on Hackage:0.2.4.8

See all snapshots buffer-builder appears in

BSD-3-Clause licensed by Chad Austin, Andy Friesen
Maintained by [email protected]
This version can be pinned in stack with:buffer-builder-0.2.4.4@sha256:0238d94c0bc024d08458f3a3fbaa6a12cc02951eeb18c76cab0e0087bb809588,5167

Module documentation for 0.2.4.4

Data.BufferBuilder is an efficient library for incrementally building up ByteStrings, one chunk at a time. Early benchmarks show it is over twice as fast as ByteString Builder, primarily because BufferBuilder is built upon an ST-style restricted monad and mutable state instead of ByteString Builder's monoidal AST.

Internally, BufferBuilder is backed by a few C functions. Examination of GHC's output shows nearly optimal code generation with no intermediate thunks -- and thus, continuation passing and its associated indirect jumps and stack traffic only occur when BufferBuilder is asked to append a non-strict ByteString.

I benchmarked four approaches with a URL encoding benchmark:

  • State monad, concatenating ByteStrings: 6.98 us

  • State monad, ByteString Builder: 2.48 us

  • Crazy explicit RealWorld baton passing with unboxed state: 28.94 us (GHC generated really awful code for this, but see the revision history for the technique)

  • C + FFI + ReaderT: 1.11 us

Using BufferBuilder is very simple:

import qualified Data.BufferBuilder as BB

let byteString = BB.runBufferBuilder $ do
      BB.appendBS "http"
      BB.appendChar8 '/'
      BB.appendBS "//"

This package also provides Data.BufferBuilder.Utf8 for generating UTF-8 buffers and Data.BufferBuilder.Json for encoding data structures into JSON.

Changes

0.2.4.4

  • Add ‘stdc++’ as an explicit library dependency. (Thanks Rob Dockins!)

0.2.4.3

  • Fix a bug where control characters (codepoints 1 through 31) were not being escaped.

0.2.4.2

  • Include test.json in sdist so benchmarks can be run from Hackage. (Thanks Ryan Scott!)

0.2.4.1

  • Fix a bug with appendEscapedJsonText and Text buffers with nonzero offsets. (Thanks Joe Lee!)

0.2.4.0

  • Add the ability to calculate the output length of a BufferBuilder without allocating or writing bytes

0.2.3.0

  • Add the ability to query the current buffer size
  • Add the ability to return a value from a BufferBuilder

0.2.2.2

  • Add the ability to percent-encode directly into a Utf8Builder
  • Add Utf8Builder.unsafeAppendBufferBuilder

0.2.2.0

  • Add the ability to encode custom types as JSON keys

0.2.1.0

  • Fix a buffer overrun in the double serializer
  • Add support for URL percent-encoding
  • Tweak the BufferWriter struct to improve code generation