Portability | portable to Hugs and GHC |
---|---|

Stability | experimental |

Maintainer | Adam Langley <agl@imperialviolet.org> |

Efficient construction of lazy bytestrings, bit by bit.

- data BitBuilder
- toLazyByteString :: BitBuilder -> ByteString
- empty :: BitBuilder
- singleton :: Bool -> BitBuilder
- append :: BitBuilder -> BitBuilder -> BitBuilder
- fromByteString :: (ByteString, Int) -> BitBuilder
- fromLazyByteString :: ByteString -> BitBuilder
- fromBits :: (Integral a, Bits a) => Int -> a -> BitBuilder
- flush :: BitBuilder

# The Builder type

data BitBuilder Source

A `BitBuilder`

is an efficient way to build lazy `ByteString`

s.
There are several functions for constructing `BitBuilder`

s, but only one
to inspect them: to extract any data, you have to turn them into lazy
`ByteString`

s using `toLazyByteString`

.

Internally, a `BitBuilder`

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

.

This is closely based on the Builder monad, but this one deals with single bits at a time.

toLazyByteString :: BitBuilder -> ByteStringSource

*O(n).* Extract a lazy `ByteString`

from a `BitBuilder`

.
The construction work takes place if and when the relevant part of
the lazy `ByteString`

is demanded.

# Constructing Builders

*O(1).* The empty BitBuilder, satisfying

singleton :: Bool -> BitBuilderSource

*O(1).* A BitBuilder taking a single bit, satisfying

`toLazyByteString`

(`singleton`

b) =`singleton`

b

append :: BitBuilder -> BitBuilder -> BitBuilderSource

*O(1).* The concatenation of two BitBuilders, an associative operation
with identity `empty`

, satisfying

`toLazyByteString`

(`append`

x y) =`append`

(`toLazyByteString`

x) (`toLazyByteString`

y)

fromByteString :: (ByteString, Int) -> BitBuilderSource

fromLazyByteString :: ByteString -> BitBuilderSource

*O(1).* A BitBuilder taking a lazy `ByteString`

, satisfying

`toLazyByteString`

(`fromLazyByteString`

bs) = bs

fromBits :: (Integral a, Bits a) => Int -> a -> BitBuilderSource

Construct a BitBuilder by taking the bottom n bits of a Bits instance. If the instance has less than n bits, this acts as if there was an infinite zero filled prefix

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

.