git.iko.soy/streamly
on master help sign in
Add documentation regarding equivalence of serialized values
commitf400dd6e647160531a1729b43fc4524809d3e788 authorAdithya Kumar <adithya@composewell.com> dateFri 8 Dec 2023, 22:16 (3 years ago) parent6d2798c
2 files changed+16−9
compare with master
unifiedsplit
core/src/Streamly/Data/MutByteArray.hs+14−5 core/src/Streamly/Internal/Data/Array.hs+2−4
core/src/Streamly/Data/MutByteArray.hs+14−5
@@ -21,9 +21,9 @@
2121-- Higher level unboxed array modules "Streamly.Data.Array" and
2222-- "Streamly.Data.MutArray" are built on top of this module. Unboxed arrays are
2323-- essentially serialized Haskell values. Array modules provide higher level
24−-- serialization routines like 'Streamly.Data.Array.pinnedSerialize'
25−-- and 'Streamly.Data.Array.deserialize' from the
26−-- "Streamly.Data.Array" module.
24+-- serialization routines like 'Streamly.Internal.Data.Array.pinnedSerialize'
25+-- and 'Streamly.Internal.Data.Array.deserialize' from the
26+-- "Streamly.Internal.Data.Array" module.
2727--
2828-- == Mutable Byte Array
2929--
@@ -55,10 +55,19 @@
5555-- and then use the type class methods to serialize and deserialize to and from
5656-- a 'MutByteArray'.
5757--
58−-- See 'Streamly.Data.Array.pinnedSerialize' and
59−-- 'Streamly.Data.Array.deserialize' for 'Array' type based
58+-- See 'Streamly.Internal.Data.Array.pinnedSerialize' and
59+-- 'Streamly.Internal.Data.Array.deserialize' for 'Array' type based
6060-- serialization.
6161--
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+--
6271module Streamly.Data.MutByteArray
6372 (
6473
core/src/Streamly/Internal/Data/Array.hs+2−4
@@ -564,12 +564,10 @@ encodeAs ps a =
564564 assertM(len == off)
565565 pure $ Array mbarr 0 off
566566
567−-- XXX The "Encoded Equivality" property is not (cannot be) true for Unbox.
568−
569567-- |
570568-- Properties:
571569-- 1. Identity: @deserialize . serialize == id@
572−-- 2. Encoded Equivality: @serialize a == serialize a@
570+-- 2. Encoded equivalence: @serialize a == serialize a@
573571{-# INLINE serialize #-}
574572serialize :: Serialize a => a -> Array Word8
575573serialize = encodeAs Unpinned
@@ -580,7 +578,7 @@ serialize = encodeAs Unpinned
580578--
581579-- Properties:
582580-- 1. Identity: @deserialize . pinnedSerialize == id@
583−-- 2. Encoded Equivality: @pinnedSerialize a == serialize a@
581+-- 2. Encoded equivalence: @pinnedSerialize a == pinnedSerialize a@
584582{-# INLINE pinnedSerialize #-}
585583pinnedSerialize :: Serialize a => a -> Array Word8
586584pinnedSerialize = encodeAs Pinned