binary-0.7.1.0: Binary serialisation for Haskell values using lazy ByteStrings

Copyright | Lennart Kolmodin, Ross Paterson
License | BSD3-style (see LICENSE)
Maintainer | Lennart Kolmodin <kolmodin@gmail.com>
Stability | experimental
Portability | portable to Hugs and GHC
Safe Haskell | Safe
Language | Haskell98

Data.Binary.Builder

Contents

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

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
- putCharUtf8 :: Char -> 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 `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.

## Unicode

putCharUtf8 :: Char -> Builder

Write a character using UTF-8 encoding.