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 Source

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

toByteString :: Builder -> ByteString Source

toLazyByteString :: Builder -> ByteString Source

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 Source

O(1). The empty Builder, satisfying

```
toLazyByteString empty = empty
```

singleton :: Word8 -> Builder Source

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

toLazyByteString (singleton b) = singleton b

append :: Builder -> Builder -> Builder Source

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 Source

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

toLazyByteString (fromByteString bs) = fromChunks [bs]

fromLazyByteString :: ByteString -> Builder Source

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

toLazyByteString (fromLazyByteString bs) = bs

Flushing the buffer state

flush :: Builder Source

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 Source

Write a Word16 in big endian format

putWord32be :: Word32 -> Builder Source

Write a Word32 in big endian format

putWord64be :: Word64 -> Builder Source

Write a Word64 in big endian format

Little-endian writes

putWord16le :: Word16 -> Builder Source

Write a Word16 in little endian format

putWord32le :: Word32 -> Builder Source

Write a Word32 in little endian format

putWord64le :: Word64 -> Builder Source

Write a Word64 in little endian format

Host-endian, unaligned writes

putWordhost :: Word -> Builder Source

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 Source

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

putWord32host :: Word32 -> Builder Source

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

putWord64host :: Word64 -> Builder Source

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.