Data.Binary.BitBuilder

Efficient construction of lazy bytestrings, bit by bit.

The Builder type

data BitBuilder

A BitBuilder is an efficient way to build lazy ByteStrings. There are several functions for constructing BitBuilders, but only one to inspect them: to extract any data, you have to turn them into lazy ByteStrings using toLazyByteString.

Internally, a BitBuilder 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 BitBuilder.

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

Instances

Show BitBuilder

Defined in Data.Binary.BitBuilder

Methods

showsPrec :: Int -> BitBuilder -> ShowS

show :: BitBuilder -> String

showList :: [BitBuilder] -> ShowS

Semigroup BitBuilder

Defined in Data.Binary.BitBuilder

Methods

(<>) :: BitBuilder -> BitBuilder -> BitBuilder

sconcat :: NonEmpty BitBuilder -> BitBuilder

stimes :: Integral b => b -> BitBuilder -> BitBuilder

Monoid BitBuilder

Defined in Data.Binary.BitBuilder

Methods

mempty :: BitBuilder

mappend :: BitBuilder -> BitBuilder -> BitBuilder

mconcat :: [BitBuilder] -> BitBuilder

toLazyByteString :: BitBuilder -> ByteString

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

empty :: BitBuilder

O(1). The empty BitBuilder, satisfying

• toLazyByteString empty = empty

singleton :: Bool -> BitBuilder

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

• toLazyByteString (singleton b) = singleton b

append :: BitBuilder -> BitBuilder -> BitBuilder

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

fromLazyByteString :: ByteString -> BitBuilder

O(1). A BitBuilder taking a lazy ByteString, satisfying

• toLazyByteString (fromLazyByteString bs) = bs

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

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

flush :: BitBuilder

O(1). Pop the ByteString we have constructed so far, if any, yielding a new chunk in the result lazy ByteString.