| Portability | portable to Hugs and GHC |
|---|---|
| Stability | experimental |
| Maintainer | Lennart Kolmodin <kolmodin@gmail.com> |
| Safe Haskell | Safe |
Data.Binary.Builder
Contents
Description
Efficient construction of lazy bytestrings.
- 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 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.
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
O(1). The empty Builder, satisfying
O(1). A Builder taking a single byte, satisfying
toLazyByteString(singletonb) =singletonb
append :: Builder -> Builder -> Builder
O(1). The concatenation of two Builders, an associative operation
with identity empty, satisfying
toLazyByteString(appendx y) =append(toLazyByteStringx) (toLazyByteStringy)
fromByteString :: ByteString -> Builder
O(1). A Builder taking a ByteString, satisfying
toLazyByteString(fromByteStringbs) =fromChunks[bs]
fromLazyByteString :: ByteString -> Builder
O(1). A Builder taking a lazy ByteString, satisfying
toLazyByteString(fromLazyByteStringbs) = bs
Flushing the buffer state
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.