Data.Binary.Builder

Copyright	Lennart Kolmodin Ross Paterson
License	BSD3-style (see LICENSE)
Maintainer	Lennart Kolmodin <[email protected]>
Stability	experimental
Portability	portable to Hugs and GHC
Safe Haskell	Safe
Language	Haskell98

The Builder type

data Builder Source

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

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 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

fromShortByteString :: ShortByteString -> Builder Source

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 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

putInt16be :: Int16 -> Builder Source

Write a Int16 in big endian format

putInt32be :: Int32 -> Builder Source

Write a Int32 in big endian format

putInt64be :: Int64 -> Builder Source

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

putInt16le :: Int16 -> Builder Source

Write a Int16 in little endian format

putInt32le :: Int32 -> Builder Source

Write a Int32 in little endian format

putInt64le :: Int64 -> Builder Source

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

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

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

putInt32host :: Int32 -> Builder Source

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

putInt64host :: Int64 -> Builder Source

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 Source

Write a character using UTF-8 encoding.

putStringUtf8 :: String -> Builder Source

Write a String using UTF-8 encoding.