Blaze.ByteString.Builder.Internal.Write

blaze-builder-0.4.2.3: Efficient buffered output.

Copyright | (c) 2010 Simon Meier (c) 2010 Jasper van der Jeugt
License | BSD3-style (see LICENSE)
Maintainer | https://github.com/blaze-builder
Stability | stable
Portability | tested on GHC only
Safe Haskell | Safe-Inferred
Language | Haskell98

Blaze.ByteString.Builder.Internal.Write

Contents

- Poking a buffer
- Writing to abuffer
- Constructing builders from writes
- Writing `Storable`s

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

- newtype Poke = Poke {
  - runPoke :: Ptr Word8 -> IO (Ptr Word8)
  }
- pokeN :: Int -> (Ptr Word8 -> IO ()) -> Poke
- data Write = Write !Int Poke
- runWrite :: Write -> Ptr Word8 -> IO (Ptr Word8)
- getBound :: Write -> Int
- getBound' :: String -> (a -> Write) -> Int
- getPoke :: Write -> Poke
- exactWrite :: Int -> (Ptr Word8 -> IO ()) -> Write
- boundedWrite :: Int -> Poke -> Write
- writeLiftIO :: (a -> Write) -> IO a -> Write
- writeIf :: (a -> Bool) -> (a -> Write) -> (a -> Write) -> a -> Write
- writeEq :: Eq a => a -> (a -> Write) -> (a -> Write) -> a -> Write
- writeOrdering :: (a -> Ordering) -> (a -> Write) -> (a -> Write) -> (a -> Write) -> a -> Write
- writeOrd :: Ord a => a -> (a -> Write) -> (a -> Write) -> (a -> Write) -> a -> Write
- fromWrite :: Write -> Builder
- fromWriteSingleton :: (a -> Write) -> a -> Builder
- fromWriteList :: (a -> Write) -> [a] -> Builder
- writeStorable :: Storable a => a -> Write
- fromStorable :: Storable a => a -> Builder
- fromStorables :: Storable a => [a] -> Builder

# Poking a buffer

newtype Poke #

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

Constructors

Poke |
Fields runPoke :: Ptr Word8 -> IO (Ptr Word8)

#### Instances

Instances details

Monoid Poke # |
Instance details Defined in Blaze.ByteString.Builder.Internal.Write Methods mempty :: Poke mappend :: Poke -> Poke -> Poke mconcat :: [Poke] -> Poke
Semigroup Poke # |
Instance details Defined in Blaze.ByteString.Builder.Internal.Write Methods (<>) :: Poke -> Poke -> Poke sconcat :: NonEmpty Poke -> Poke stimes :: Integral b => b -> Poke -> Poke

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

`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 #

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

Instances details

Monoid Write # |
Instance details Defined in Blaze.ByteString.Builder.Internal.Write Methods mempty :: Write mappend :: Write -> Write -> Write mconcat :: [Write] -> Write
Semigroup Write # |
Instance details Defined in Blaze.ByteString.Builder.Internal.Write Methods (<>) :: Write -> Write -> Write sconcat :: NonEmpty Write -> Write stimes :: Integral b => b -> Write -> Write

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

Run the `Poke` action of a write.

getBound :: Write -> Int #

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

getBound' #

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 #

Extract the `Poke` action of a write.

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

`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 #

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

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

`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 #

`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 #

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 #

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 #

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 #

Create a builder that execute a single `Write`.

fromWriteSingleton :: (a -> Write) -> a -> Builder #

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

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

# Writing `Storable`s

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.