binary-0.8.5.1: 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 constructions of lazy bytestrings.

This now re-exports `Builder`.

Synopsis

- data Builder :: *
- toLazyByteString :: Builder -> ByteString
- empty :: Builder
- singleton :: Word8 -> Builder
- append :: Builder -> Builder -> Builder
- fromByteString :: ByteString -> Builder
- fromLazyByteString :: ByteString -> Builder
- fromShortByteString :: ShortByteString -> Builder
- flush :: Builder
- putWord16be :: Word16 -> Builder
- putWord32be :: Word32 -> Builder
- putWord64be :: Word64 -> Builder
- putInt16be :: Int16 -> Builder
- putInt32be :: Int32 -> Builder
- putInt64be :: Int64 -> Builder
- putWord16le :: Word16 -> Builder
- putWord32le :: Word32 -> Builder
- putWord64le :: Word64 -> Builder
- putInt16le :: Int16 -> Builder
- putInt32le :: Int32 -> Builder
- putInt64le :: Int64 -> Builder
- putWordhost :: Word -> Builder
- putWord16host :: Word16 -> Builder
- putWord32host :: Word32 -> Builder
- putWord64host :: Word64 -> Builder
- putInthost :: Int -> Builder
- putInt16host :: Int16 -> Builder
- putInt32host :: Int32 -> Builder
- putInt64host :: Int64 -> Builder
- putCharUtf8 :: Char -> Builder
- putStringUtf8 :: String -> Builder

# The Builder type

data Builder :: * Source #

`Builder`s denote sequences of bytes. They are `Monoid`s where `mempty` is the zero-length sequence and `mappend` is concatenation, which runs in O(1).

Instances

Semigroup Builder |
Methods (<>) :: Builder -> Builder -> Builder Source # sconcat :: NonEmpty Builder -> Builder Source # stimes :: Integral b => b -> Builder -> Builder Source #
Monoid Builder |
Methods mempty :: Builder Source # mappend :: Builder -> Builder -> Builder Source # mconcat :: [Builder] -> Builder Source #

toLazyByteString :: Builder -> ByteString Source #

Execute a `Builder` and return the generated chunks as a lazy `ByteString`. The work is performed lazy, i.e., only when a chunk of the lazy `ByteString` is forced.

# 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

fromShortByteString :: ShortByteString -> Builder #

O(n). A builder taking `ShortByteString` and copy it to a Builder, satisfying

- @`toLazyByteString` (`fromShortByteString` bs) = `fromChunks` [`fromShort` bs]

# Flushing the buffer state

flush :: Builder Source #

Flush the current buffer. This introduces a chunk boundary.

# 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

putInt16be :: Int16 -> Builder #

Write a Int16 in big endian format

putInt32be :: Int32 -> Builder #

Write a Int32 in big endian format

putInt64be :: Int64 -> Builder #

Write a Int64 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

putInt16le :: Int16 -> Builder #

Write a Int16 in little endian format

putInt32le :: Int32 -> Builder #

Write a Int32 in little endian format

putInt64le :: Int64 -> Builder #

Write a Int64 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.

putInthost :: Int -> 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 Int 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.

putInt16host :: Int16 -> Builder #

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

putInt32host :: Int32 -> Builder #

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

putInt64host :: Int64 -> Builder #

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

## Unicode

putCharUtf8 :: Char -> Builder #

Write a character using UTF-8 encoding.

putStringUtf8 :: String -> Builder #

Write a String using UTF-8 encoding.