Data.ByteString.Builder.Prim

A fmap-like operator for builder primitives, both bounded and fixed size.

Builder primitives are contravariant so it's like the normal fmap, but backwards (look at the type). (If it helps to remember, the operator symbol is like ($) but backwards.)

We can use it for example to prepend and/or append fixed values to an primitive.

 import Data.ByteString.Builder.Prim as P
showEncoding ((\x -> ('\'', (x, '\''))) >$< fixed3) 'x' = "'x'"
  where
    fixed3 = P.char7 >*< P.char7 >*< P.char7

Note that the rather verbose syntax for composition stems from the requirement to be able to compute the size / size bound at compile time.

Encode an IEEE Double using 16 nibbles.

Encode an IEEE Float using 8 nibbles.

Decimal encoding of an Int16.

Encode a Int16 using 4 nibbles.

Decimal encoding of an Int32.

Encode a Int32 using 8 nibbles.

Decimal encoding of an Int64.

Encode a Int64 using 16 nibbles.

Decimal encoding of an Int8.

Encode a Int8 using 2 nibbles (hexadecimal digits).

Decimal encoding of an Int.

Decimal encoding of a Word16.

Hexadecimal encoding of a Word16.

Encode a Word16 using 4 nibbles.

Decimal encoding of a Word32.

Hexadecimal encoding of a Word32.

Encode a Word32 using 8 nibbles.

Decimal encoding of a Word64.

Hexadecimal encoding of a Word64.

Encode a Word64 using 16 nibbles.

Decimal encoding of a Word8.

Hexadecimal encoding of a Word8.

Encode a Word8 using 2 nibbles (hexadecimal digits).

Decimal encoding of a Word.

Hexadecimal encoding of a Word.

Char8 encode a Char.

UTF-8 encode a Char.

A null-terminated ASCII encoded CString. Null characters are not representable.

A null-terminated UTF-8 encoded CString. Null characters can be encoded as 0xc0 0x80.

Create a Builder that encodes values with the given BoundedPrim.

We rewrite consecutive uses of primBounded such that the bound-checks are fused. For example,

primBounded (word32 c1) `mappend` primBounded (word32 c2)

is rewritten such that the resulting Builder checks only once, if ther are at 8 free bytes, instead of checking twice, if there are 4 free bytes. This optimization is not observationally equivalent in a strict sense, as it influences the boundaries of the generated chunks. However, for a user of this library it is observationally equivalent, as chunk boundaries of a LazyByteString can only be observed through the internal interface. Moreover, we expect that all primitives write much fewer than 4kb (the default short buffer size). Hence, it is safe to ignore the additional memory spilled due to the more aggressive buffer wrapping introduced by this optimization.

Encode a value with a FixedPrim.

Create a Builder that encodes a list of values consecutively using a BoundedPrim for each element. This function is more efficient than

mconcat . map (primBounded w)

or

foldMap (primBounded w)

because it moves several variables out of the inner loop.

Encode a list of values from left-to-right with a FixedPrim.

Encode the least 7-bits of a Char using the ASCII encoding.

Encode a Double in big endian format.

Encode a Double in little endian format.

Encode a Float in big endian format.

Encode a Float in little endian format.

Encoding Int16s in big endian format.

Encoding Int16s in little endian format.

Encoding Int32s in big endian format.

Encoding Int32s in little endian format.

Encoding Int64s in big endian format.

Encoding Int64s in little endian format.

Encoding single signed bytes as-is.

Encoding Word16s in big endian format.

Encoding Word16s in little endian format.

Encoding Word32s in big endian format.

Encoding Word32s in little endian format.

Encoding Word64s in big endian format.

Encoding Word64s in little endian format.

Encoding single unsigned bytes as-is.

A builder primitive that always results in sequence of bytes that is no longer than a pre-determined bound.

Create a Builder that encodes each Word8 of a StrictByteString using a BoundedPrim. For example, we can write a Builder that filters a StrictByteString as follows.

import qualified Data.ByteString.Builder.Prim as P

filterBS p = P.condB p (P.liftFixedToBounded P.word8) P.emptyB

Heavy inlining. Encode all bytes of a StrictByteString from left-to-right with a FixedPrim. This function is quite versatile. For example, we can use it to construct a Builder that maps every byte before copying it to the buffer to be filled.

mapToBuilder :: (Word8 -> Word8) -> S.StrictByteString -> Builder
mapToBuilder f = primMapByteStringFixed (contramapF f word8)

We can also use it to hex-encode a StrictByteString as shown by the byteStringHex example above.

Chunk-wise application of primMapByteStringBounded.

Heavy inlining. Encode all bytes of a LazyByteString from left-to-right with a FixedPrim.

Create a Builder that encodes a sequence generated from a seed value using a BoundedPrim for each sequence element.

Encode a list of values represented as an unfoldr with a FixedPrim.

Encode a Double in native host order and host endianness.

Encode a Float in native host order and host endianness. Values written this way are not portable to different endian machines, without conversion.

Encoding Int16s in native host order and host endianness.

Encoding Int32s in native host order and host endianness.

Encoding Int64s in native host order and host endianness.

Encode a single native machine Int. The Ints is encoded in host order, host endian form, for the machine you are on. On a 64 bit machine the Int is an 8 byte value, on a 32 bit machine, 4 bytes. Values encoded this way are not portable to different endian or integer sized machines, without conversion.

Encoding Word16s in native host order and host endianness.

Encoding Word32s in native host order and host endianness.

Encoding Word64s in native host order and host endianness.

Encode a single native machine Word. The Words is encoded in host order, host endian form, for the machine you are on. On a 64 bit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes. Values encoded this way are not portable to different endian or word sized machines, without conversion.

A pairing/concatenation operator for builder primitives, both bounded and fixed size.

For example,

toLazyByteString (primFixed (char7 >*< char7) ('x','y')) = "xy"

We can combine multiple primitives using >*< multiple times.

toLazyByteString (primFixed (char7 >*< char7 >*< char7) ('x',('y','z'))) = "xyz"

Conditionally select a BoundedPrim. For example, we can implement the ASCII primitive that drops characters with Unicode codepoints above 127 as follows.

charASCIIDrop = condB (< '\128') (liftFixedToBounded char7) emptyB
 

Encode an Either value using the first BoundedPrim for Left values and the second BoundedPrim for Right values.

Note that the functions eitherB, pairB, and contramapB (written below using >$<) suffice to construct BoundedPrims for all non-recursive algebraic datatypes. For example,

maybeB :: BoundedPrim () -> BoundedPrim a -> BoundedPrim (Maybe a)
maybeB nothing just = maybe (Left ()) Right >$< eitherB nothing just
 

The BoundedPrim that always results in the zero-length sequence.

The FixedPrim that always results in the zero-length sequence.

Lift a FixedPrim to a BoundedPrim.

A builder primitive that always results in a sequence of bytes of a pre-determined, fixed size.