git.iko.soy/streamly
on master help sign in
Add documentation regarding equivalence of serialized values
f400dd6Adithya Kumar
core/src/Streamly/Data/MutByteArray.hs+14−5
compare with master
unifiedsplit
@@ -21,9 +21,9 @@
21-- Higher level unboxed array modules "Streamly.Data.Array" and
21-- Higher level unboxed array modules "Streamly.Data.Array" and
22-- "Streamly.Data.MutArray" are built on top of this module. Unboxed arrays are
22-- "Streamly.Data.MutArray" are built on top of this module. Unboxed arrays are
23-- essentially serialized Haskell values. Array modules provide higher level
23-- essentially serialized Haskell values. Array modules provide higher level
24−-- serialization routines like 'Streamly.Data.Array.pinnedSerialize'
24+-- serialization routines like 'Streamly.Internal.Data.Array.pinnedSerialize'
25−-- and 'Streamly.Data.Array.deserialize' from the
25+-- and 'Streamly.Internal.Data.Array.deserialize' from the
26−-- "Streamly.Data.Array" module.
26+-- "Streamly.Internal.Data.Array" module.
27--
27--
28-- == Mutable Byte Array
28-- == Mutable Byte Array
29--
29--
@@ -55,10 +55,19 @@
55-- and then use the type class methods to serialize and deserialize to and from
55-- and then use the type class methods to serialize and deserialize to and from
56-- a 'MutByteArray'.
56-- a 'MutByteArray'.
57--
57--
58−-- See 'Streamly.Data.Array.pinnedSerialize' and
58+-- See 'Streamly.Internal.Data.Array.pinnedSerialize' and
59−-- 'Streamly.Data.Array.deserialize' for 'Array' type based
59+-- 'Streamly.Internal.Data.Array.deserialize' for 'Array' type based
60-- serialization.
60-- serialization.
61--
61--
62+-- == Comparing serialized values
63+--
64+-- When using the `Unbox` type class the same value may result in differing
65+-- serialized bytes because of unused uninitialized data in case of sum types.
66+-- Therefore, byte comparison of serialized values is not reliable.
67+--
68+-- However, the 'Serialize' type class guarantees that the serialized values
69+-- are always exactly the same and byte comparison of serialized is reliable.
70+--
62module Streamly.Data.MutByteArray
71module Streamly.Data.MutByteArray
63 (
72 (
64
73
core/src/Streamly/Internal/Data/Array.hs+2−4
@@ -564,12 +564,10 @@ encodeAs ps a =
564 assertM(len == off)
564 assertM(len == off)
565 pure $ Array mbarr 0 off
565 pure $ Array mbarr 0 off
566
566
567−-- XXX The "Encoded Equivality" property is not (cannot be) true for Unbox.
568−
569-- |
567-- |
570-- Properties:
568-- Properties:
571-- 1. Identity: @deserialize . serialize == id@
569-- 1. Identity: @deserialize . serialize == id@
572−-- 2. Encoded Equivality: @serialize a == serialize a@
570+-- 2. Encoded equivalence: @serialize a == serialize a@
573{-# INLINE serialize #-}
571{-# INLINE serialize #-}
574serialize :: Serialize a => a -> Array Word8
572serialize :: Serialize a => a -> Array Word8
575serialize = encodeAs Unpinned
573serialize = encodeAs Unpinned
@@ -580,7 +578,7 @@ serialize = encodeAs Unpinned
580--
578--
581-- Properties:
579-- Properties:
582-- 1. Identity: @deserialize . pinnedSerialize == id@
580-- 1. Identity: @deserialize . pinnedSerialize == id@
583−-- 2. Encoded Equivality: @pinnedSerialize a == serialize a@
581+-- 2. Encoded equivalence: @pinnedSerialize a == pinnedSerialize a@
584{-# INLINE pinnedSerialize #-}
582{-# INLINE pinnedSerialize #-}
585pinnedSerialize :: Serialize a => a -> Array Word8
583pinnedSerialize :: Serialize a => a -> Array Word8
586pinnedSerialize = encodeAs Pinned
584pinnedSerialize = encodeAs Pinned