From fd1494e9c3928ea13820f5e91748822a19a5abea Mon Sep 17 00:00:00 2001 From: The8472 Date: Thu, 18 Nov 2021 02:00:53 +0100 Subject: [PATCH 1/2] Document non-guarantees for Hash Dependence on endianness and type sizes was reported for enum discriminants in #74215 but it is a more general issue since for example the default implementation of `Hasher::write_usize` uses native endianness. Additionally the implementations of library types are occasionally changed as their internal fields change or hashing gets optimized. --- library/core/src/hash/mod.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/library/core/src/hash/mod.rs b/library/core/src/hash/mod.rs index 540160bc4c2a4..44d517d6c9318 100644 --- a/library/core/src/hash/mod.rs +++ b/library/core/src/hash/mod.rs @@ -164,6 +164,19 @@ mod sip; /// `0xFF` byte to the `Hasher` so that the values `("ab", "c")` and `("a", /// "bc")` hash differently. /// +/// ## Portability +/// +/// Due to differences in endianness and type sizes data fed by `Hash` to a `Hasher` +/// should not be considered portable across platforms. Additionally the data passed by most +/// standard library types should not be considered stable between compiler versions. +/// +/// This means tests shouldn't probe hard-coded hash values or data fed to a `Hasher` and +/// instead should check consistency with `Eq`. +/// +/// Serialization formats intended to he portable between platforms or compiler versions should +/// either avoid encoding hashes or only rely on `Hash` and `Hasher` implementations that +/// provide additional guarantees. +/// /// [`HashMap`]: ../../std/collections/struct.HashMap.html /// [`HashSet`]: ../../std/collections/struct.HashSet.html /// [`hash`]: Hash::hash From 53fc69f87c623cf3085127530b3f6a810bfd5a4a Mon Sep 17 00:00:00 2001 From: the8472 Date: Tue, 23 Nov 2021 23:55:05 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> --- library/core/src/hash/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/hash/mod.rs b/library/core/src/hash/mod.rs index 44d517d6c9318..3ff84cc9672eb 100644 --- a/library/core/src/hash/mod.rs +++ b/library/core/src/hash/mod.rs @@ -166,14 +166,14 @@ mod sip; /// /// ## Portability /// -/// Due to differences in endianness and type sizes data fed by `Hash` to a `Hasher` +/// Due to differences in endianness and type sizes, data fed by `Hash` to a `Hasher` /// should not be considered portable across platforms. Additionally the data passed by most /// standard library types should not be considered stable between compiler versions. /// /// This means tests shouldn't probe hard-coded hash values or data fed to a `Hasher` and /// instead should check consistency with `Eq`. /// -/// Serialization formats intended to he portable between platforms or compiler versions should +/// Serialization formats intended to be portable between platforms or compiler versions should /// either avoid encoding hashes or only rely on `Hash` and `Hasher` implementations that /// provide additional guarantees. ///