Copyright	Lennart Kolmodin Ross Paterson Galois Inc. 2009
License	BSD3-style (see LICENSE)
Maintainer	Trevor Elliott <trevor@galois.com>
Stability	Portability :
Safe Haskell	None
Language	Haskell98

Data.Serialize.Builder

Contents

The Builder type
Constructing Builders
Flushing the buffer state
Derived Builders

Description

Efficient construction of lazy bytestrings.

Synopsis

The Builder type

data Builder #

A Builder is an efficient way to build lazy ByteStrings. There are several functions for constructing Builders, but only one to inspect them: to extract any data, you have to turn them into lazy ByteStrings using toLazyByteString.

Internally, a Builder constructs a lazy Bytestring by filling byte arrays piece by piece. As each buffer is filled, it is 'popped' off, to become a new chunk of the resulting lazy ByteString. All this is hidden from the user of the Builder.

Instances

Monoid Builder #
Methods mempty :: Builder # mappend :: Builder -> Builder -> Builder # mconcat :: [Builder] -> Builder #

toByteString :: Builder -> ByteString #

toLazyByteString :: Builder -> ByteString #

O(n). Extract a lazy ByteString from a Builder. The construction work takes place if and when the relevant part of the lazy ByteString is demanded.

Constructing Builders

empty :: Builder #

O(1). The empty Builder, satisfying

```
toLazyByteString empty = empty
```

singleton :: Word8 -> Builder #

O(1). A Builder taking a single byte, satisfying

toLazyByteString (singleton b) = singleton b

append :: Builder -> Builder -> Builder #

O(1). The concatenation of two Builders, an associative operation with identity empty, satisfying

toLazyByteString (append x y) = append (toLazyByteString x) (toLazyByteString y)

fromByteString :: ByteString -> Builder #

O(1). A Builder taking a ByteString, satisfying

toLazyByteString (fromByteString bs) = fromChunks [bs]

fromLazyByteString :: ByteString -> Builder #

O(1). A Builder taking a lazy ByteString, satisfying

toLazyByteString (fromLazyByteString bs) = bs

Flushing the buffer state

flush :: Builder #

O(1). Pop the ByteString we have constructed so far, if any, yielding a new chunk in the result lazy ByteString.

Derived Builders

Big-endian writes

putWord16be :: Word16 -> Builder #

Write a Word16 in big endian format

putWord32be :: Word32 -> Builder #

Write a Word32 in big endian format

putWord64be :: Word64 -> Builder #

Write a Word64 in big endian format

Little-endian writes

putWord16le :: Word16 -> Builder #

Write a Word16 in little endian format

putWord32le :: Word32 -> Builder #

Write a Word32 in little endian format

putWord64le :: Word64 -> Builder #

Write a Word64 in little endian format

Host-endian, unaligned writes

putWordhost :: Word -> Builder #

O(1). A Builder taking a single native machine word. The word is written in host order, host endian form, for the machine you're on. On a 64 bit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes. Values written this way are not portable to different endian or word sized machines, without conversion.

putWord16host :: Word16 -> Builder #

Write a Word16 in native host order and host endianness. 2 bytes will be written, unaligned.

putWord32host :: Word32 -> Builder #

Write a Word32 in native host order and host endianness. 4 bytes will be written, unaligned.

putWord64host :: Word64 -> Builder #

Write a Word64 in native host order. On a 32 bit machine we write two host order Word32s, in big endian form. 8 bytes will be written, unaligned.