| ghc-binary-0.5.0.2: Binary serialisation for Haskell values using lazy ByteStrings | Contents | Index

Data.Binary.Builder

Portability | portable to Hugs and GHC
Stability | experimental
Maintainer | Lennart Kolmodin <kolmodin@dtek.chalmers.se>

Contents

The Builder type
Constructing Builders
Flushing the buffer state
Derived Builders
  Big-endian writes
  Little-endian writes
  Host-endian, unaligned writes

Description
Efficient construction of lazy bytestrings.
Synopsis

data Builder
toLazyByteString :: Builder -> ByteString
empty :: Builder
singleton :: Word8 -> Builder
append :: Builder -> Builder -> Builder
fromByteString :: ByteString -> Builder
fromLazyByteString :: ByteString -> Builder
flush :: Builder
putWord16be :: Word16 -> Builder
putWord32be :: Word32 -> Builder
putWord64be :: Word64 -> Builder
putWord16le :: Word16 -> Builder
putWord32le :: Word32 -> Builder
putWord64le :: Word64 -> Builder
putWordhost :: Word -> Builder
putWord16host :: Word16 -> Builder
putWord32host :: Word32 -> Builder
putWord64host :: Word64 -> Builder

The Builder type
data Builder

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

Internally, a `Builder` constructs a lazy L.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

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.
Produced by Haddock version 2.6.1