----------------------------------------------------------------------------- -- | -- Module : Blaze.ByteString.Builder -- Copyright : (c) 2010 Jasper Van der Jeugt & Simon Meier -- License : BSD3-style (see LICENSE) -- -- Maintainer : Simon Meier <iridcode@gmail.com> -- Stability : experimental -- Portability : tested on GHC only -- -- "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. ----------------------------------------------------------------------------- module Blaze.ByteString.Builder ( -- * The 'Builder' type Builder -- * Creating builders , module Blaze.ByteString.Builder.Int , module Blaze.ByteString.Builder.Word , module Blaze.ByteString.Builder.ByteString , flush -- * Executing builders , toLazyByteString , toLazyByteStringWith , toByteString , toByteStringIO , toByteStringIOWith -- * 'Write's , Write , fromWrite , fromWriteSingleton , fromWriteList , writeToByteString -- ** Writing 'Storable's , writeStorable , fromStorable , fromStorables ) where import Blaze.ByteString.Builder.Internal import Blaze.ByteString.Builder.Int import Blaze.ByteString.Builder.Word import Blaze.ByteString.Builder.ByteString