blaze-builder-0.4.0.2: Efficient buffered output.

Copyright(c) 2010 Simon Meier (c) 2010 Jasper van der Jeugt
LicenseBSD3-style (see LICENSE)
MaintainerLeon Smith <leon@melding-monads.com>
Stabilityexperimental
Portabilitytested on GHC only
Safe HaskellNone
LanguageHaskell98

Blaze.ByteString.Builder.Internal.Write

Contents

Description

A general and efficient write type that allows for the easy construction of builders for (smallish) bounded size writes to a buffer.

FIXME: Improve documentation.

Synopsis

Poking a buffer

newtype Poke Source #

Changing a sequence of bytes starting from the given pointer. Pokes are the most primitive buffer manipulation. In most cases, you don't use the explicitely but as part of a Write, which also tells how many bytes will be changed at most.

Constructors

Poke 

Fields

Instances

pokeN :: Int -> (Ptr Word8 -> IO ()) -> Poke Source #

pokeN size io creates a write that denotes the writing of size bytes to a buffer using the IO action io. Note that io MUST write EXACTLY size bytes to the buffer!

Writing to abuffer

data Write Source #

A write of a bounded number of bytes.

When defining a function write :: a -> Write for some a, then it is important to ensure that the bound on the number of bytes written is data-independent. Formally,

 forall x y. getBound (write x) = getBound (write y)

The idea is that this data-independent bound is specified such that the compiler can optimize the check, if there are enough free bytes in the buffer, to a single subtraction between the pointer to the next free byte and the pointer to the end of the buffer with this constant bound of the maximal number of bytes to be written.

Constructors

Write !Int Poke 

Instances

runWrite :: Write -> Ptr Word8 -> IO (Ptr Word8) Source #

Run the Poke action of a write.

getBound :: Write -> Int Source #

Extract the maximal number of bytes that this write could write.

getBound' Source #

Arguments

:: String

Name of caller: for debugging purposes.

-> (a -> Write) 
-> Int 

Extract the maximal number of bytes that this write could write in any case. Assumes that the bound of the write is data-independent.

getPoke :: Write -> Poke Source #

Extract the Poke action of a write.

exactWrite :: Int -> (Ptr Word8 -> IO ()) -> Write Source #

exactWrite size io creates a bounded write that can later be converted to a builder that writes exactly size bytes. Note that io MUST write EXACTLY size bytes to the buffer!

boundedWrite :: Int -> Poke -> Write Source #

boundedWrite size write creates a bounded write from a write that does not write more than size bytes.

writeLiftIO :: (a -> Write) -> IO a -> Write Source #

writeLiftIO io write creates a write executes the io action to compute the value that is then written.

writeIf :: (a -> Bool) -> (a -> Write) -> (a -> Write) -> a -> Write Source #

writeIf p wTrue wFalse x creates a Write with a Poke equal to wTrue x, if p x and equal to wFalse x otherwise. The bound of this new Write is the maximum of the bounds for either Write. This yields a data independent bound, if the bound for wTrue and wFalse is already data independent.

writeEq :: Eq a => a -> (a -> Write) -> (a -> Write) -> a -> Write Source #

Compare the value to a test value and use the first write action for the equal case and the second write action for the non-equal case.

writeOrdering :: (a -> Ordering) -> (a -> Write) -> (a -> Write) -> (a -> Write) -> a -> Write Source #

TODO: Test this. It might well be too difficult to use. FIXME: Better name required!

writeOrd :: Ord a => a -> (a -> Write) -> (a -> Write) -> (a -> Write) -> a -> Write Source #

A write combinator useful to build decision trees for deciding what value to write with a constant bound on the maximal number of bytes written.

Constructing builders from writes

fromWrite :: Write -> Builder Source #

Create a builder that execute a single Write.

fromWriteList :: (a -> Write) -> [a] -> Builder Source #

Construct a Builder writing a list of data one element at a time.

Writing Storables

writeStorable :: Storable a => a -> Write Source #

Write a storable value.

fromStorable :: Storable a => a -> Builder Source #

A builder that serializes a storable value. No alignment is done.

fromStorables :: Storable a => [a] -> Builder Source #

A builder that serializes a list of storable values by writing them consecutively. No alignment is done. Parsing information needs to be provided externally.