From f531b8122ebd7b07a50198b14727337763d05707 Mon Sep 17 00:00:00 2001
From: pierwill <pierwill@users.noreply.github.com>
Date: Fri, 1 Oct 2021 12:39:08 -0500
Subject: [PATCH] docs: `std::hash::Hash` should ensure prefix-free data

Closes #89429
---
 library/core/src/hash/mod.rs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/library/core/src/hash/mod.rs b/library/core/src/hash/mod.rs
index da3f20d18e51..83cb85843b6e 100644
--- a/library/core/src/hash/mod.rs
+++ b/library/core/src/hash/mod.rs
@@ -153,9 +153,19 @@ mod sip;
 /// Thankfully, you won't need to worry about upholding this property when
 /// deriving both [`Eq`] and `Hash` with `#[derive(PartialEq, Eq, Hash)]`.
 ///
+/// ## Prefix collisions
+///
+/// Implementations of `hash` should ensure that the data they
+/// pass to the `Hasher` are prefix-free. That is, different concatenations
+/// of the same data should not produce the same output.
+/// For example, the standard implementation of [`Hash` for `&str`][impl] passes an extra
+/// `0xFF` byte to the `Hasher` so that the values `("ab", "c")` and `("a",
+/// "bc")` hash differently.
+///
 /// [`HashMap`]: ../../std/collections/struct.HashMap.html
 /// [`HashSet`]: ../../std/collections/struct.HashSet.html
 /// [`hash`]: Hash::hash
+/// [impl]: ../../std/primitive.str.html#impl-Hash
 #[stable(feature = "rust1", since = "1.0.0")]
 #[rustc_diagnostic_item = "Hash"]
 pub trait Hash {