Safe Haskell | Safe-Inferred |
---|
Defines a type-safe 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
- preserialize :: TypeInformation -> TypeInformation
- 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 aSource
data TypeFormat Source
Different ways of including/verifying type information of serialized messages.
Untyped | Include no type information.
|
Hashed32 | Compare types by their hash values (using the MurmurHash2 algorithm).
|
Hashed64 | Like |
Shown | Compare
|
Full | Compare the full representation of a data type.
|
Useful general helpers
mapTyped :: Typeable b => (a -> b) -> Typed a -> Typed bSource
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 un-mapTyped
id
precache
values.
reValue :: (a -> a) -> Typed a -> Typed aSource
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
).
preserialize :: TypeInformation -> TypeInformationSource
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 8 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.
Typed serialization
Encoding
encodeTyped :: (Typeable a, Binary a) => TypeFormat -> a -> ByteStringSource
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,
is equivalent to
encodeTyped
format value
. However, encode
(typed
format value)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.
encodeTypedLike :: (Typeable a, Binary a) => Typed a -> a -> ByteStringSource
Deprecated: encodeTyped
now caches automatically for all types
Decoding
decodeTyped :: (Typeable a, Binary a) => ByteString -> Either String aSource
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 meta-information of the consumed binary data.
- Typed cousin of
decodeOrFail
. * LikedecodeTyped
, but with additional data.
unsafeDecodeTyped :: (Typeable a, Binary a) => ByteString -> aSource