Library for efficiently building up buffers, one piece at a time
|Version on this page:||0.2.4.6|
|LTS Haskell 20.23:||0.2.4.8|
|Stackage Nightly 2023-06-04:||0.2.4.8|
|Latest on Hackage:||0.2.4.8|
Module documentation for 0.2.4.6
Data.BufferBuilder is an efficient library for incrementally building
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
Data.BufferBuilder.Json for encoding data structures into JSON.
- Fix package compilation on GHC 7.8 and 7.10. (Thanks Xia Li-yao!)
- Add Semigroup instance for ObjectBuilder. (Thanks Dan Fithian!)
- Add ‘stdc++’ as an explicit library dependency. (Thanks Rob Dockins!)
- Fix a bug where control characters (codepoints 1 through 31) were not being escaped.
- Include test.json in sdist so benchmarks can be run from Hackage. (Thanks Ryan Scott!)
- Fix a bug with appendEscapedJsonText and Text buffers with nonzero offsets. (Thanks Joe Lee!)
- Add the ability to calculate the output length of a BufferBuilder without allocating or writing bytes
- Add the ability to query the current buffer size
- Add the ability to return a value from a BufferBuilder
- Add the ability to percent-encode directly into a Utf8Builder
- Add Utf8Builder.unsafeAppendBufferBuilder
- Add the ability to encode custom types as JSON keys
- Fix a buffer overrun in the double serializer
- Add support for URL percent-encoding
- Tweak the BufferWriter struct to improve code generation