| |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
Description | |||||||||||||||||||||||||||||||||
Blaze.ByteString.Builder is the main module, which you should import as a user of the blaze-builder library. import Blaze.ByteString.Builder It provides you with a type Builder that allows to efficiently construct lazy bytestrings with a large average chunk size. Intuitively, a Builder denotes the construction of a part of a lazy bytestring. Builders can either be created using one of the primitive combinators in Blaze.ByteString.Builder.Write or by using one of the predefined combinators for standard Haskell values (see the exposed modules of this package). Concatenation of builders is done using mappend from the Monoid typeclass. Here is a small example that serializes a list of strings using the UTF-8 encoding. import Blaze.ByteString.Builder.Char.Utf8 strings :: [String] strings = replicate 10000 "Hello there!" The function fromString creates a Builder denoting the UTF-8 encoded argument. Hence, UTF-8 encoding and concatenating all strings can be done follows. concatenation :: Builder concatenation = mconcat $ map fromString strings The function toLazyByteString can be used to execute a Builder and obtain the resulting lazy bytestring. result :: L.ByteString result = toLazyByteString concatenation The result is a lazy bytestring containing 10000 repetitions of the string "Hello there!" encoded using UTF-8. The corresponding 120000 bytes are distributed among three chunks of 32kb and a last chunk of 6kb. A note on history. This serialization library was inspired by the Data.Binary.Builder module 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. | |||||||||||||||||||||||||||||||||
Synopsis | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
The Builder type | |||||||||||||||||||||||||||||||||
data Builder | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
Creating builders | |||||||||||||||||||||||||||||||||
module Blaze.ByteString.Builder.Int | |||||||||||||||||||||||||||||||||
module Blaze.ByteString.Builder.Word | |||||||||||||||||||||||||||||||||
module Blaze.ByteString.Builder.ByteString | |||||||||||||||||||||||||||||||||
flush :: Builder | |||||||||||||||||||||||||||||||||
Output all data written in the current buffer and start a new chunk. The use uf this function depends on how the resulting bytestrings are consumed. flush is possibly not very useful in non-interactive scenarios. However, it is kept for compatibility with the builder provided by Data.Binary.Builder. When using toLazyByteString to extract a lazy ByteString from a Builder, this means that a new chunk will be started in the resulting lazy ByteString. The remaining part of the buffer is spilled, if the reamining free space is smaller than the minimal desired buffer size. | |||||||||||||||||||||||||||||||||
Executing builders | |||||||||||||||||||||||||||||||||
toLazyByteString :: Builder -> ByteString | |||||||||||||||||||||||||||||||||
Extract the lazy ByteString from the builder by running it with default buffer sizes. Use this function, if you do not have any special considerations with respect to buffer sizes. toLazyByteString b = toLazyByteStringWith defaultBufferSize defaultMinimalBufferSize defaultFirstBufferSize b L.empty Note that toLazyByteString is a Monoid homomorphism. toLazyByteString mempty == mempty toLazyByteString (x `mappend` y) == toLazyByteString x `mappend` toLazyByteString y However, in the second equation, the left-hand-side is generally faster to execute. | |||||||||||||||||||||||||||||||||
toLazyByteStringWith | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
toByteString :: Builder -> ByteString | |||||||||||||||||||||||||||||||||
Run the builder to construct a strict bytestring containing the sequence of bytes denoted by the builder. This is done by first serializing to a lazy bytestring and then packing its chunks to a appropriately sized strict bytestring. toByteString = packChunks . toLazyByteString Note that toByteString is a Monoid homomorphism. toByteString mempty == mempty toByteString (x `mappend` y) == toByteString x `mappend` toByteString y However, in the second equation, the left-hand-side is generally faster to execute. | |||||||||||||||||||||||||||||||||
toByteStringIO :: (ByteString -> IO ()) -> Builder -> IO () | |||||||||||||||||||||||||||||||||
Run the builder with a defaultBufferSized buffer and execute the given IO action whenever the buffer is full or gets flushed. toByteStringIO = toByteStringIOWith defaultBufferSize This is a Monoid homomorphism in the following sense. toByteStringIO io mempty == return () toByteStringIO io (x `mappend` y) == toByteStringIO io x >> toByteStringIO io y | |||||||||||||||||||||||||||||||||
toByteStringIOWith | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
Writes | |||||||||||||||||||||||||||||||||
data Write | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
fromWrite :: Write -> Builder | |||||||||||||||||||||||||||||||||
fromWriteSingleton :: (a -> Write) -> a -> Builder | |||||||||||||||||||||||||||||||||
fromWriteList :: (a -> Write) -> [a] -> Builder | |||||||||||||||||||||||||||||||||
Construct a Builder writing a list of data one element at a time. | |||||||||||||||||||||||||||||||||
Writing Storables | |||||||||||||||||||||||||||||||||
writeStorable :: Storable a => a -> Write | |||||||||||||||||||||||||||||||||
Write a storable value. | |||||||||||||||||||||||||||||||||
fromStorable :: Storable a => a -> Builder | |||||||||||||||||||||||||||||||||
A builder that serializes a storable value. No alignment is done. | |||||||||||||||||||||||||||||||||
fromStorables :: Storable a => [a] -> Builder | |||||||||||||||||||||||||||||||||
A builder that serializes a list of storable values by writing them consecutively. No alignment is done. Parsing information needs to be provided externally. | |||||||||||||||||||||||||||||||||
Produced by Haddock version 2.6.0 |