From fd1494e9c3928ea13820f5e91748822a19a5abea Mon Sep 17 00:00:00 2001 From: The8472 Date: Thu, 18 Nov 2021 02:00:53 +0100 Subject: [PATCH] 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 540160bc4c2a..44d517d6c931 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