Mention the Borrow guarantee on the Hash implementations for Array and Vec

To remind people like me who forget about it and send PRs to make them different, and to (probably) get a test failure if the code is changed to no longer uphold it.

1 files changed, 17 insertions, 0 deletions

diff --git a/library/core/src/array/mod.rs b/library/core/src/array/mod.rs
index e25d006d213..aa7f71cf85b 100644
--- a/library/core/src/array/mod.rs
+++ b/library/core/src/array/mod.rs
@@ -139,6 +139,23 @@ impl<'a, T, const N: usize> TryFrom<&'a mut [T]> for &'a mut [T; N] {
     }
 }
 
+/// The hash of an array is the same as that of the corresponding slice,
+/// as required by the `Borrow` implementation.
+///
+/// ```
+/// use std::hash::{BuildHasher, Hash, Hasher};
+///
+/// fn hash_of(x: impl Hash, b: &impl BuildHasher) -> u64 {
+///     let mut h = b.build_hasher();
+///     x.hash(&mut h);
+///     h.finish()
+/// }
+///
+/// let b = std::collections::hash_map::RandomState::new();
+/// let a: [u8; 3] = [0xa8, 0x3c, 0x09];
+/// let s: &[u8] = &[0xa8, 0x3c, 0x09];
+/// assert_eq!(hash_of(a, &b), hash_of(s, &b));
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Hash, const N: usize> Hash for [T; N] {
     fn hash<H: hash::Hasher>(&self, state: &mut H) {