Data.ByteString.Builder.Prim.Internal

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.

The size of the sequences of bytes generated by this FixedPrim.

The type used for sizes and sizeBounds of sizes.

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

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.

Encode a pair by encoding its first component and then its second component.

The bound on the size of sequences of bytes generated by this BoundedPrim.

Convert a FixedPrim to a BoundedPrim.

Select an implementation depending on bitness. Throw a compile time error if bitness is neither 32 nor 64.

Encode a pair by encoding its first component and then its second component.

Change a BoundedPrim such that it first applies a function to the value to be encoded.

Note that BoundedPrims are Contravariant http://hackage.haskell.org/package/contravariant. Hence, the following laws hold.

contramapB id = id
contramapB f . contramapB g = contramapB (g . f)

Change a primitives such that it first applies a function to the value to be encoded.

Note that primitives are Contravariant http://hackage.haskell.org/package/contravariant. Hence, the following laws hold.

contramapF id = id
contramapF f . contramapF g = contramapF (g . f)