binary-typed 0.2.0.0 → 0.2.0.1
raw patch · 3 files changed
+76/−70 lines, 3 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
Files
- binary-typed.cabal +1/−1
- src/Data/Binary/Typed.hs +16/−15
- src/Data/Binary/Typed/Internal.hs +59/−54
binary-typed.cabal view
@@ -1,5 +1,5 @@ name: binary-typed-version: 0.2.0.0+version: 0.2.0.1 synopsis: Type-safe binary serialization Description: `Binary` serialization tagged with type information, allowing for
src/Data/Binary/Typed.hs view
@@ -47,24 +47,24 @@ -- | 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.+-- 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, @'mapTyped' 'id'@--- can be used to un-'precache' values.+-- Note: this destroys 'precache'd information, so that values have to be+-- 'precache'd again if desired. As a consequence, @'mapTyped' 'id'@+-- can be used to un-'precache' values. mapTyped :: Typeable b => (a -> b) -> Typed a -> Typed b mapTyped f (Typed ty x) = typed (getFormat ty) (f x) -- | 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.+-- 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@).+-- Can be seen as a more efficient 'mapTyped' in case @f@ is an endomorphism+-- (i.e. has type @a -> a@). reValue :: (a -> a) -> Typed a -> Typed a reValue f (Typed ty x) = Typed ty (f x) @@ -113,7 +113,7 @@ -- | Decode a typed value, throwing an error at runtime on failure.--- Typed cousin of 'Data.Binary.decode'.+-- Typed cousin of 'Data.Binary.decode'. -- -- @ -- encoded = 'encodeTyped' 'Full' ("hello", 1 :: 'Int', 2.34 :: 'Double')@@ -132,10 +132,11 @@ -- | Safely decode data, yielding 'Either' an error 'String' or the value,--- along with meta-information of the consumed binary data.+-- along with meta-information of the consumed binary data. ----- * Typed cousin of 'Data.Binary.decodeOrFail'.--- * Like 'decodeTyped', but with additional data.+-- * Typed cousin of 'Data.Binary.decodeOrFail'.+--+-- * Like 'decodeTyped', but with additional data. decodeTypedOrFail :: (Typeable a, Binary a) => BSL.ByteString -> Either (BSL.ByteString, ByteOffset, String)@@ -147,7 +148,7 @@ -- | Safely decode data, yielding 'Either' an error 'String' or the value.--- Equivalent to 'decodeTypedOrFail' stripped of the non-essential data.+-- Equivalent to 'decodeTypedOrFail' stripped of the non-essential data. -- -- @ -- encoded = 'encodeTyped' 'Full' ("hello", 1 :: 'Int', 2.34 :: 'Double')
src/Data/Binary/Typed/Internal.hs view
@@ -53,8 +53,8 @@ -- ^ Type information stored alongside a value to be serialized, so that the--- recipient can do consistency checks. See 'TypeFormat' for more detailed--- information on the fields.+-- recipient can do consistency checks. See 'TypeFormat' for more detailed+-- information on the fields. data TypeInformation = Untyped' | Hashed32' Hash32 | Hashed64' Hash64@@ -83,7 +83,7 @@ -- | A hash value of a 'TypeRep'. Currently a 32-bit value created using--- the MurmurHash2 algorithm.+-- the MurmurHash2 algorithm. newtype Hash32 = Hash32 Word32 deriving (Eq, Ord, Show, Generic) instance Binary Hash32@@ -91,7 +91,7 @@ -- | A hash value of a 'TypeRep'. Currently a 64-bit value created using--- the MurmurHash2 algorithm.+-- the MurmurHash2 algorithm. newtype Hash64 = Hash64 Word64 deriving (Eq, Ord, Show, Generic) instance Binary Hash64@@ -99,7 +99,7 @@ -- | A value suitable to be typechecked using the contained extra type--- information.+-- information. data Typed a = Typed TypeInformation a -- ^ Using this data constructor directly is unsafe, as it allows -- construction of ill-typed 'Typed' data. Use the 'typed' smart@@ -112,8 +112,8 @@ (show x) -- | Ensures data is decoded as the appropriate type with high or total--- confidence (depending on with what 'TypeFormat' the 'Typed' was--- constructed).+-- confidence (depending on with what 'TypeFormat' the 'Typed' was+-- constructed). instance (Binary a, Typeable a) => Binary (Typed a) where get = do (ty, value) <- get either fail return (typecheck (Typed ty value))@@ -123,19 +123,19 @@ -- | 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 'BSL.ByteString'requires its length to--- be included in the final serialization, yielding a 8-byte overhead for the--- required 'Data.Int.Int64', and one for the tag of what was serialized--- ("shown or full?").+-- 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 'BSL.ByteString' requires its length to+-- be included in the final serialization, yielding a 8-byte overhead for the+-- required 'Data.Int.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).+-- 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 'Data.Binary.Typed.encodeTyped' more efficient; the source--- there also makes a good usage example.+-- Used to make 'Data.Binary.Typed.encodeTyped' more efficient; the source+-- there also makes a good usage example. preserialize :: TypeInformation -> TypeInformation preserialize x@(Cached' _) = x preserialize x@(Untyped' ) = x@@ -150,9 +150,9 @@ -- | Preserializes type information if its encoded byte length is larger than--- an arbitrary threshold. Less efficient than 'preserialize' since it--- always preserializes and always calculates the encoded version no matter--- what.+-- an arbitrary threshold. Less efficient than 'preserialize' since it+-- always preserializes and always calculates the encoded version no matter+-- what. preserialize' :: TypeInformation -> TypeInformation preserialize' x | BSL.length encoded > 10*9 = Cached' encoded | otherwise = x@@ -171,52 +171,57 @@ Untyped -- | Compare types by their hash values (using the MurmurHash2- -- algorithm).+ -- algorithm). --- -- * Requires five bytes more compared to using 'Binary' directly for- -- the type information (one to tag as 'Hashed32', four for the- -- hash value)- -- * Subject to false positive due to hash collisions, although in- -- practice this should almost never happen.- -- * Type errors cannot tell the provided type ("Expected X, received- -- type with hash H")+ -- * Requires five bytes more compared to using 'Binary' directly for+ -- the type information (one to tag as 'Hashed32', four for the+ -- hash value)+ --+ -- * Subject to false positive due to hash collisions, although in+ -- practice this should almost never happen.+ --+ -- * Type errors cannot tell the provided type ("Expected X, received+ -- type with hash H") | Hashed32 -- | Like 'Hashed32', but uses a 64-bit hash value. --- -- * Requires nine bytes more compared to using 'Binary'.- -- * Hash collisions are even less likely to occur than with- -- 'Hashed32'.+ -- * Requires nine bytes more compared to using 'Binary'.+ --+ -- * Hash collisions are even less likely to occur than with+ -- 'Hashed32'. | Hashed64 -- | Compare 'String' representation of types, obtained by calling- -- 'show' on the 'TypeRep', and also include a hash value- -- (like 'Hashed32'). The former is mostly for readable error- -- messages, the latter provides better collision resistance.+ -- 'show' on the 'TypeRep', and also include a hash value+ -- (like 'Hashed32'). The former is mostly for readable error+ -- messages, the latter provides better collision resistance. --- -- * Data size larger than 'Hashed32', but usually smaller than- -- 'Full'.- -- * Both the hash and the shown type must match to satisfy the- -- typechecker.- -- * Useful type errors ("expected X, received Y"). All types are- -- shown unqualified though, making @Foo.X@ and @Bar.X@ look- -- identical in error messages. Remember this when you get a- -- seemingly silly error "expected Foo, but given Foo".+ -- * Data size larger than 'Hashed32', but usually smaller than+ -- 'Full'.+ --+ -- * Both the hash and the shown type must match to satisfy the+ -- typechecker.+ --+ -- * Useful type errors ("expected X, received Y"). All types are+ -- shown unqualified though, making @Foo.X@ and @Bar.X@ look+ -- identical in error messages. Remember this when you get a+ -- seemingly silly error "expected Foo, but given Foo". | Shown -- | Compare the full representation of a data type. --- -- * More verbose than 'Hashed' and 'Shown'. As a rule of thumb,- -- transmitted data is roughly the same as 'Shown', but all names- -- are fully qualified (package, module, type name).- -- * Correct comparison (no false positives). An semi-exception here- -- is when types change between package versions:- -- @package-1.0 Foo.X@ and @package-1.1 Foo.X@ count as the same- -- type.- -- * Useful type errors ("expected X, received Y"). All types are- -- shown unqualified though, making @Foo.X@ and @Bar.X@ look- -- identical in error messages. Remember this when you get a- -- seemingly silly error "expected Foo, but given Foo".+ -- * More verbose than 'Hashed' and 'Shown'. As a rule of thumb,+ -- transmitted data is roughly the same as 'Shown', but all names+ -- are fully qualified (package, module, type name).+ -- * Correct comparison (no false positives). An semi-exception here+ -- is when types change between package versions:+ -- @package-1.0 Foo.X@ and @package-1.1 Foo.X@ count as the same+ -- type.+ -- * Useful type errors ("expected X, received Y"). All types are+ -- shown unqualified though, making @Foo.X@ and @Bar.X@ look+ -- identical in error messages. Remember this when you get a+ -- seemingly silly error "expected Foo, but given Foo". | Full deriving (Eq, Ord, Show)