type Size = Int
The type used for sizes and sizeBounds of sizes.
*Warning:* this module is internal. If you find that you need it please contact the maintainers and explain what you are trying to do and discuss what you would need in the public API. It is important that you do this as the module may not be exposed at all in future releases.
The maintainers are glad to accept patches for further standard encodings of standard Haskell values.
If you need to write your own builder primitives, then be aware that you are
writing code with all safety belts off; i.e.,
*this is the code that might make your application vulnerable to buffer-overflow attacks!*
The Data.ByteString.Builder.Prim.Tests module provides you with
utilities for testing your encodings thoroughly.
type Size = IntThe type used for sizes and sizeBounds of sizes.
data FixedPrim aA builder primitive that always results in a sequence of bytes of a pre-determined, fixed size.
fixedPrim :: Int -> (a -> Ptr Word8 -> IO ()) -> FixedPrim asize :: FixedPrim a -> IntThe size of the sequences of bytes generated by this FixedPrim.
runF :: FixedPrim a -> a -> Ptr Word8 -> IO ()emptyF :: FixedPrim aThe FixedPrim that always results in the zero-length sequence.
contramapF :: (b -> a) -> FixedPrim a -> FixedPrim bChange 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)pairF :: FixedPrim a -> FixedPrim b -> FixedPrim (a, b)Encode a pair by encoding its first component and then its second component.
storableToF :: forall a. Storable a => FixedPrim aDeprecated since @bytestring-0.12.1.0@.\n\nThis function is dangerous in the presence of internal padding\nand makes naive assumptions about alignment.\n\n * For a primitive Haskell type like 'Int64', use the\n corresponding primitive like 'Data.ByteString.Builder.Prim.int64Host'.\n * For other types, it is recommended to manually write a small\n function that performs the necessary unaligned write\n and zeroes or removes any internal padding bits.
data BoundedPrim aA builder primitive that always results in sequence of bytes that is no longer than a pre-determined bound.
boundedPrim :: Int -> (a -> Ptr Word8 -> IO (Ptr Word8)) -> BoundedPrim asizeBound :: BoundedPrim a -> IntThe bound on the size of sequences of bytes generated by this BoundedPrim.
runB :: BoundedPrim a -> a -> Ptr Word8 -> IO (Ptr Word8)emptyB :: BoundedPrim aThe BoundedPrim that always results in the zero-length sequence.
contramapB :: (b -> a) -> BoundedPrim a -> BoundedPrim bChange 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)pairB :: BoundedPrim a -> BoundedPrim b -> BoundedPrim (a, b)Encode a pair by encoding its first component and then its second component.
eitherB :: BoundedPrim a -> BoundedPrim b -> BoundedPrim (Either a b)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
condB :: (a -> Bool) -> BoundedPrim a -> BoundedPrim a -> BoundedPrim aConditionally 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' 'Data.ByteString.Builder.Prim.char7') 'emptyB'
toB :: FixedPrim a -> BoundedPrim aConvert a FixedPrim to a BoundedPrim.
liftFixedToBounded :: FixedPrim a -> BoundedPrim aLift a FixedPrim to a BoundedPrim.
(>$<) :: Contravariant f => (b -> a) -> f a -> f bA 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.char7Note that the rather verbose syntax for composition stems from the requirement to be able to compute the size / size bound at compile time.
(>*<) :: Monoidal f => f a -> f b -> f (a, b)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"caseWordSize_32_64 :: a -> a -> aSelect an implementation depending on bitness. Throw a compile time error if bitness is neither 32 nor 64.
boudedPrim :: Int -> (a -> Ptr Word8 -> IO (Ptr Word8)) -> BoundedPrim aUse 'boundedPrim' instead
instance Contravariant FixedPriminstance Contravariant BoundedPriminstance Monoidal FixedPriminstance Monoidal BoundedPrimCommunity contribution. The service has not verified this documentation. The generator reported 11 diagnostics.
Target: Linux on x86-64. Some inferred types and resolved links are not available.
Generator: aihc-haddock-aa6debbd-web-3
Metadata snapshot: 35f1f56d3dce7f0c7af322ec05f2fba4d1a04564930537462a4ba21b64b756fa
Open the dependency plan · Download the documentation model