Safe Haskell  SafeInferred 

Language  Haskell2010 
Defines a typesafe Binary
instance to ensure data is
decoded with the type it was serialized from.
For usage information, see the Data.Binary.Typed.Tutorial module.
 data Typed a
 typed :: Typeable a => TypeFormat > a > Typed a
 data TypeFormat
 erase :: Typed a > a
 mapTyped :: Typeable b => (a > b) > Typed a > Typed b
 reValue :: (a > a) > Typed a > Typed a
 reType :: Typeable a => TypeFormat > Typed a > Typed a
 precache :: Typed a > Typed a
 encodeTyped :: (Typeable a, Binary a) => TypeFormat > a > ByteString
 encodeTypedLike :: (Typeable a, Binary a) => Typed a > a > ByteString
 decodeTyped :: (Typeable a, Binary a) => ByteString > Either String a
 decodeTypedOrFail :: (Typeable a, Binary a) => ByteString > Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)
 unsafeDecodeTyped :: (Typeable a, Binary a) => ByteString > a
Core functions
A value suitable to be typechecked using the contained extra type information.
typed :: Typeable a => TypeFormat > a > Typed a Source
data TypeFormat Source
Different ways of including/verifying type information of serialized messages.
Untyped  Include no type information.

Hashed  Compare types by their hash values (using the MurmurHash2 algorithm).

Shown  Compare 
Full  Compare the full representation of a data type.

Useful general helpers
mapTyped :: Typeable b => (a > b) > Typed a > Typed b Source
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 precache
d information, so that values have to be
precache
d again if desired. As a consequence,
can be used to unmapTyped
id
precache
values.
reValue :: (a > a) > Typed a > Typed a Source
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
).
precache :: Typed a > Typed a Source
Calculate the serialization of a TypeInformation
and store it in a
Typed
value so it does not have to be recalculated on every call to
encode
.
This is typically applied to a dummy value created using typed
and
the desired TypeFormat
; the actual data is then inserted using
reValue
, which is how
encodeTyped
works.
Typed serialization
Encoding
encodeTyped :: (Typeable a, Binary a) => TypeFormat > a > ByteString Source
Encode a Typeable
value to ByteString
that includes type
information. If at all possible, prefer the more efficient encodeTypedLike
though.
encodeTyped
format value =encode
(typed
format value)
encodeTypedLike :: (Typeable a, Binary a) => Typed a > a > ByteString Source
Version of encodeTyped
that avoids recomputing the type representation
of the input by using the one already contained in the first parameter.
This is usually much more efficient than using encode
, having a
computational cost similar to using Binary
directly.
encodeTypedLike
ty x  is observationally identical toencode
(reValue
(const
x) ty)
This function is intended to generate new encoding functions like so:
encodeInt ::Int
>ByteString
encodeInt =encodeTypedLike
(typed
Full
0)
Decoding
decodeTyped :: (Typeable a, Binary a) => ByteString > Either String a Source
Safely decode data, yielding Either
an error String
or the value.
Equivalent to decodeTypedOrFail
stripped of the nonessential 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
)
decodeTypedOrFail :: (Typeable a, Binary a) => ByteString > Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) Source
Safely decode data, yielding Either
an error String
or the value,
along with metainformation of the consumed binary data.
 Typed cousin of
decodeOrFail
.  Like
decodeTyped
, but with additional data.
unsafeDecodeTyped :: (Typeable a, Binary a) => ByteString > a Source
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 errorunsafeDecodeTyped
encoded :: (Char
,Int
,Double
)