Module documentation for 0.4.0.1
This library allows to efficiently serialize Haskell values to lazy bytestrings with a large average chunk size. The large average chunk size allows to make good use of cache prefetching in later processing steps (e.g. compression) and reduces the system call overhead when writing the resulting lazy bytestring to a file or sending it over the network.
This library was inspired by the module Data.Binary.Builder provided by the binary package. It was originally developed with the specific needs of the blaze-html package in mind. Since then it has been restructured to serve as a drop-in replacement for Data.Binary.Builder, which it improves upon both in speed as well as expressivity.
To see the improvements in speed, run the throughput benchmark, which measures serialization speeds for writing Word8, Word16, Word32 and Word64 in different endian formats and different chunk sizes, using the command
or run the list serialization comparison benchmark
Checkout the combinators in the module "Blaze.ByteString.Builder.Write" to see the improvements in expressivity. This module allows to incorporate efficient primitive buffer manipulations as parts of a builder. We use this facility in the 'blaze-html' HTML templating library to allow for the efficient serialization of HTML escaped and UTF-8 encoded characters.
- Gain compatibility with the Semigroup/Monoid proposal
- Add Word8 HTML escaping builders
- Speed up `fromHtmlEscapedText` and `fromHtmlEscapedLazyText`
- Fixed warnings on GHC 7.10, courtesy of Mikhail Glushenkov.
- Tightened the version constraints on the bytestring package for GHC 7.8
- This is now a compatibility shim for the new bytestring builder. Most
of the old internal modules are gone. See this blog post for more
- The 'Blaze.ByteString.Builder.Html.Utf8.fromHtmlEscaped*' functions now
strip out any ASCII control characters present in their inputs. See
<https://github.com/lpsmith/blaze-builder/issues/1> for more
- exposed the 'Buffer' constructor to enable keeping around a pool of
- added 'writeToByteString' to construct a strict bytestring in a single
step. We can actually view 'Write's as strict-bytestring builders.
- Changed imports of Foreign.Unsafe to make it GHC 7.8 compatible
- -Wall clean on GHC 7.0 - 7.6
- Widened dependencies on text and bytestring
- Fix build warning in Blaze.ByteString.Builder.Word
(contributed by Greg Weber)
- Remove comparison to the 'text' library encoding functions of
'Blaze.Builder.Char.Utf8.fromLazyText'. Bryan O'Sullivan reported that on
his 64-bit system with GHC 7.0.3 the 'text' library is 5x faster than the
- Renamings in internal modules: WriteIO -> Poke and associated functions.
- Fixed bug: appending to 'chunkedTransferEncoding somebuilder' also encoded
the appended builder, which is obviously wrong.
- Fixed bug: 'chunkedTransferTerminator' is now correctly set to "0\r\n\r\n".
- Add 'MonoPatBinds' language extension to all relevant files to solve the
issues caused by GHC bug http://hackage.haskell.org/trac/ghc/ticket/4498
- Reexport 'Write' datatype and 'fromWriteList', 'fromWriteSingleton',
'fromWrite' functions together with writes and builders for storables.
- Add 'MonoPatBinds' language extension to (hopefully) solve the issues
caused by GHC bug http://hackage.haskell.org/trac/ghc/ticket/4498
Incorporated several design changes:
- Writable buffer range is now represented in a packed form. This improves
speed slightly, as less currying is used.
- Writes are abstracted such that their internal representation can be
exchanged without breaking other library code.
- Writes are represented in a form that allows for efficient monoid
instances for branching code like UTF-8 encoding. For single character
encoding this results currently in a slight slowdown due to GHC not
recognizing the strictness of the returned value. This will be fixed in
- BuildSteps support returning a result in `Done`, which enables to
implement a `Put` monad using CPS.
- chunked list writes were removed, as they result in worse performance
when writing non-trivial lists. (cf. benchmarks)
- An internal buffering abstraction is introduced, which is used both
by the adaption of the `binary` package, as well as by the
`blaze-builder-enumeratee` package, to execute puts and builders.
It will be used later also by the execution functions of the
Implemented new functionality
- `Blaze.ByteString.Builder.HTTP` provides a builder transformer for
doing in-buffer chunked HTTP encoding of an arbitary other builder.
- `Blaze.ByteString.Builder.Char8` provides functions to serialize the
lower 8-bits of characters similiar to what `Data.ByteString.Char8`
provides for bytestrings.
Loosen 'text' dependency to '>= 0.10 && < 0.12'
Fixed bug: use ' instead of ' for HTML escaping '
Added a missing benchmark file.
Heavily restructured 'blaze-builder' such that 'Blaze.ByteString.Builder' serves as
a drop-in replacement of 'binary:Data.Binary.Builder' which it improves upon
with respect to both speed as well as expressivity. See the documentation and
the benchmarks for details on improvements and new functionality.
Changed module structure:
Blaze.ByteString.Builder.Core -> Blaze.ByteString.Builder
Blaze.ByteString.Builder.Utf8 -> Blaze.ByteString.Builder.Char.Utf8
Blaze.ByteString.Builder.Html -> Blaze.ByteString.Builder.Html.Utf8
Changed function names:
writeByte -> writeWord8
fromByte -> fromWord8
fromWriteList -> fromWrite1List
Possibly performance sensitive implementation changes:
- 'fromByteString' and 'fromLazyByteString' check now if a direct insertion
of the bytestring(s) would be cheaper than copying it. See their
documentation on how to recover the old behaviour.
'empty' : use 'mempty' instead
'singleton': use 'fromWord8' instead
'append' : use 'mappend' instead
This is the first version of 'blaze-builder'. It is explicitely targeted at
fast generation of UTF-8 encoded HTML documents in the 'blaze-html' and the
'hamlet' HTML templating libraries.