A value suitable to be typechecked using the contained extra type information.

Construct a Typed value using the chosen type format.

Example:

value = typed Full ("hello", 1 :: Int, 2.34 :: Double)
encded = encode value

The decode site can now verify whether decoding happens with the right type.

Different ways of including/verifying type information of serialized messages.

Extract the value of a Typed, i.e. strip off the explicit type information.

This function is safe to use for all Typed values created by the public API, since all construction sites ensure the actual type matches the contained type description.

erase (typed format x) == x

Modify the value contained in a Typed, keeping the same sort of type representation. In other words, calling mapTyped on something that is typed using Hashed will yield a Hashed value again.

Note: this destroys precached information, so that values have to be precached again if desired. As a consequence, mapTyped id can be used to un-precache values.

Change the value contained in a Typed, leaving the type representation unchanged. This can be useful to avoid recomputation of the included type information, and can improve performance significantly if many individual messages are serialized.

Can be seen as a more efficient mapTyped in case f is an endomorphism (i.e. has type a -> a).

Change the way a type is represented inside a Typed value.

reType format x = typed format (erase x)

Sometimes it can be beneficial to serialize the type information in advance, so that the maybe costly serialization step does not have to be repeated on every invocation of encode. Preserialization comes at a price though, as the directly contained ByteString requires its length to be included in the final serialization, yielding a 8-byte overhead for the required Int64, and one for the tag of what was serialized ("shown or full?").

This function calculates the serialized version of TypeInformation in cases where the required 9 bytes are negligible (determined by an arbitrary threshold, currently 10*9 bytes).

Used to make encodeTyped more efficient; the source there also makes a good usage example.

Encode a Typeable value to ByteString that includes type information. This function is useful to create specialized typed encoding functions, because the type information is cached and does not need to be recalculated on every serialization.

Observationally, encodeTyped format value is equivalent to encode (typed format value). However, encodeTyped does the type information related calculations in advance and shares the results between future invocations of it, making it much more efficient to serialize many values of the same type.

Safely decode data, yielding Either an error String or the value. Equivalent to decodeTypedOrFail stripped of the non-essential data.

encoded = encodeTyped Full ("hello", 1 :: Int, 2.34 :: Double)

-- Right <value>:
decodeTyped encoded :: Either String (String, Int, Double)

-- Left "Type error: expected (Char, Int, Double), got (String, Int, Double)"
decodeTyped encoded :: Either String (Char, Int, Double)

Safely decode data, yielding Either an error String or the value, along with meta-information of the consumed binary data.

• Typed cousin of decodeOrFail.
• Like decodeTyped, but with additional data.

Decode a typed value, throwing an error at runtime on failure. Typed cousin of decode.

encoded = encodeTyped Full ("hello", 1 :: Int, 2.34 :: Double)

-- <value>
unsafeDecodeTyped encoded :: (String, Int, Double)

-- (Descriptive) runtime error
unsafeDecodeTyped encoded :: (Char, Int, Double)