//! 通用哈希支持。
//!
//! 该模块提供了一种计算值的 [哈希][hash] 的通用方法。
//! 哈希最常与 [`HashMap`] 和 [`HashSet`] 一起使用。
//!
//! [hash]: https://en.wikipedia.org/wiki/Hash_function
//! [`HashMap`]: ../../std/collections/struct.HashMap.html
//! [`HashSet`]: ../../std/collections/struct.HashSet.html
//!
//! 使类型可哈希化的最简单方法是使用 `#[derive(Hash)]`：
//!
//! # Examples
//!
//! ```rust
//! use std::collections::hash_map::DefaultHasher;
//! use std::hash::{Hash, Hasher};
//!
//! #[derive(Hash)]
//! struct Person {
//!     id: u32,
//!     name: String,
//!     phone: u64,
//! }
//!
//! let person1 = Person {
//!     id: 5,
//!     name: "Janet".to_string(),
//!     phone: 555_666_7777,
//! };
//! let person2 = Person {
//!     id: 5,
//!     name: "Bob".to_string(),
//!     phone: 555_666_7777,
//! };
//!
//! assert!(calculate_hash(&person1) != calculate_hash(&person2));
//!
//! fn calculate_hash<T: Hash>(t: &T) -> u64 {
//!     let mut s = DefaultHasher::new();
//!     t.hash(&mut s);
//!     s.finish()
//! }
//! ```
//!
//! 如果您需要更多地控制值的散列方式，则需要实现 [`Hash`] trait：
//!
//!
//! ```rust
//! use std::collections::hash_map::DefaultHasher;
//! use std::hash::{Hash, Hasher};
//!
//! struct Person {
//!     id: u32,
//!     # #[allow(dead_code)]
//!     name: String,
//!     phone: u64,
//! }
//!
//! impl Hash for Person {
//!     fn hash<H: Hasher>(&self, state: &mut H) {
//!         self.id.hash(state);
//!         self.phone.hash(state);
//!     }
//! }
//!
//! let person1 = Person {
//!     id: 5,
//!     name: "Janet".to_string(),
//!     phone: 555_666_7777,
//! };
//! let person2 = Person {
//!     id: 5,
//!     name: "Bob".to_string(),
//!     phone: 555_666_7777,
//! };
//!
//! assert_eq!(calculate_hash(&person1), calculate_hash(&person2));
//!
//! fn calculate_hash<T: Hash>(t: &T) -> u64 {
//!     let mut s = DefaultHasher::new();
//!     t.hash(&mut s);
//!     s.finish()
//! }
//! ```

#![stable(feature = "rust1", since = "1.0.0")]

use crate::fmt;
use crate::marker;

#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated)]
pub use self::sip::SipHasher;

#[unstable(feature = "hashmap_internals", issue = "none")]
#[allow(deprecated)]
#[doc(hidden)]
pub use self::sip::SipHasher13;

mod sip;

/// 可散列的类型。
///
/// 实现 `Hash` 的类型可以通过 [`Hasher`] 的实例进行 [`hash`] 化。
///
/// ## 实现 `Hash`
///
/// 如果所有字段都要实现 `Hash`，则可以用 `#[derive(Hash)]` 派生 `Hash`。
/// 产生的哈希将是在每个字段上调用 [`hash`] 的值的组合。
///
/// ```
/// #[derive(Hash)]
/// struct Rustacean {
///     name: String,
///     country: String,
/// }
/// ```
///
/// 如果您需要更多地控制值的散列方式，则当然可以自己实现 `Hash` trait：
///
/// ```
/// use std::hash::{Hash, Hasher};
///
/// struct Person {
///     id: u32,
///     name: String,
///     phone: u64,
/// }
///
/// impl Hash for Person {
///     fn hash<H: Hasher>(&self, state: &mut H) {
///         self.id.hash(state);
///         self.phone.hash(state);
///     }
/// }
/// ```
///
/// ## `Hash` 和 `Eq`
///
/// 同时实现 `Hash` 和 [`Eq`] 时，保持以下属性很重要：
///
/// ```text
/// k1 == k2 -> hash(k1) == hash(k2)
/// ```
///
/// 换句话说，如果两个键相等，则它们的哈希也必须相等。
/// [`HashMap`] 和 [`HashSet`] 都依赖于这种行为。
///
/// 值得庆幸的是，在使用 `#[derive(PartialEq, Eq, Hash)]` 派生 [`Eq`] 和 `Hash` 时，您不必担心维护此属性。
///
/// ## 前缀冲突
///
/// `hash` 的实现应该确保它们传递给 `Hasher` 的数据是无前缀的。
/// 也就是说，不相等的值应该导致写入两个不同的值序列，并且这两个序列中的任何一个都不应该是另一个序列的前缀。
///
/// 例如，[`Hash` for `&str`][impl] 的标准实现将额外的 `0xFF` 字节传递给 `Hasher`，以便值 `("ab", "c")` 和 `("a", "bc")` 哈希不同。
///
/// ## Portability
///
/// 由于字节序和类型大小的差异，由 `Hash` 提供给 `Hasher` 的数据不应被视为跨平台可移植的。
/// 此外，大多数标准库类型传递的数据在不同的编译器版本之间不应该被认为是稳定的。
///
/// 这意味着测试不应探测硬编码的哈希值或提供给 `Hasher` 的数据，而应检查与 `Eq` 的一致性。
///
/// 旨在在平台或编译器版本之间可移植的序列化格式应避免编码哈希或仅依赖提供额外保证的 `Hash` 和 `Hasher` 实现。
///
///
/// [`HashMap`]: ../../std/collections/struct.HashMap.html
/// [`HashSet`]: ../../std/collections/struct.HashSet.html
/// [`hash`]: Hash::hash
/// [impl]: ../../std/primitive.str.html#impl-Hash-for-str
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_diagnostic_item = "Hash"]
pub trait Hash {
    /// 将该值输入给定的 [`Hasher`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::hash_map::DefaultHasher;
    /// use std::hash::{Hash, Hasher};
    ///
    /// let mut hasher = DefaultHasher::new();
    /// 7920.hash(&mut hasher);
    /// println!("Hash is {:x}!", hasher.finish());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn hash<H: Hasher>(&self, state: &mut H);

    /// 将这种类型的切片送入给定的 [`Hasher`] 中。
    ///
    /// 此方法是为了方便起见，但它的实现也明确未指定。
    /// 它不能保证等同于 [`hash`] 的重复调用，并且 [`Hash`] 的实现应该记住这一点，如果在 [`PartialEq`] 实现中没有将 6 视为整个单元，则调用 [`hash`] 本身。
    ///
    /// 例如，一个 [`VecDeque`] 实现可能天真地调用 [`as_slices`] 然后 [`hash_slice`] 对每个调用 [`hash_slice`]，但这是错误的，因为两个切片可以随调用更改为 [`make_contiguous`] 而不会影响 [`PartialEq`] 结果。
    ///
    /// 由于这些切片不被视为单一单元，而是更大双端队列的一部分，因此无法使用此方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::hash_map::DefaultHasher;
    /// use std::hash::{Hash, Hasher};
    ///
    /// let mut hasher = DefaultHasher::new();
    /// let numbers = [6, 28, 496, 8128];
    /// Hash::hash_slice(&numbers, &mut hasher);
    /// println!("Hash is {:x}!", hasher.finish());
    /// ```
    ///
    /// [`VecDeque`]: ../../std/collections/struct.VecDeque.html
    /// [`as_slices`]: ../../std/collections/struct.VecDeque.html#method.as_slices
    /// [`make_contiguous`]: ../../std/collections/struct.VecDeque.html#method.make_contiguous
    /// [`hash`]: Hash::hash
    /// [`hash_slice`]: Hash::hash_slice
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "hash_slice", since = "1.3.0")]
    fn hash_slice<H: Hasher>(data: &[Self], state: &mut H)
    where
        Self: Sized,
    {
        for piece in data {
            piece.hash(state)
        }
    }
}

// 单独的模块，用于从 prelude 重导出 `Hash` 宏，而无需 `Hash` trait。
pub(crate) mod macros {
    /// 派生宏，生成 `Hash` trait 的实现。
    #[rustc_builtin_macro]
    #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
    #[allow_internal_unstable(core_intrinsics)]
    pub macro Hash($item:item) {
        /* compiler built-in */
    }
}
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[doc(inline)]
pub use macros::Hash;

/// 对任意字节流进行散列的 trait。
///
/// `Hasher` 的实例通常表示在对数据进行哈希处理时更改的状态。
///
/// `Hasher` 提供了一个相当基本的接口，用于检索生成的散列 (使用 [`finish`])，并将整数和字节片写入实例 (使用 [`write`] 和 [`write_u8`] 等)。
/// 大多数情况下，`Hasher` 实例与 [`Hash`] trait 结合使用。
///
/// 这个 trait 不保证如何定义各种 `write_*` 方法，并且 [`Hash`] 的实现不应假设它们以一种或另一种方式工作。
/// 例如，您不能假设一个 [`write_u32`] 调用等同于 [`write_u8`] 的四个调用。
/// 您也不能假设相邻的 `write` 调用是合并的，所以有可能，例如，
///
/// ```
/// # fn foo(hasher: &mut impl std::hash::Hasher) {
/// hasher.write(&[1, 2]);
/// hasher.write(&[3, 4, 5, 6]);
/// # }
/// ```
///
/// and
///
/// ```
/// # fn foo(hasher: &mut impl std::hash::Hasher) {
/// hasher.write(&[1, 2, 3, 4]);
/// hasher.write(&[5, 6]);
/// # }
/// ```
///
/// 最终产生不同的哈希值。
///
/// 因此，为了产生相同的散列值，[`Hash`] 实现必须确保对等价项进行完全相同的调用序列 -- 相同的方法具有相同的参数以相同的顺序。
///
///
/// # Examples
///
/// ```
/// use std::collections::hash_map::DefaultHasher;
/// use std::hash::Hasher;
///
/// let mut hasher = DefaultHasher::new();
///
/// hasher.write_u32(1989);
/// hasher.write_u8(11);
/// hasher.write_u8(9);
/// hasher.write(b"Huh?");
///
/// println!("Hash is {:x}!", hasher.finish());
/// ```
///
/// [`finish`]: Hasher::finish
/// [`write`]: Hasher::write
/// [`write_u8`]: Hasher::write_u8
/// [`write_u32`]: Hasher::write_u32
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Hasher {
    /// 返回到目前为止写入的值的哈希值。
    ///
    /// 尽管名称如此，该方法不会重置哈希器的内部状态。
    /// 额外的 [`write`] 将从当前值继续。
    /// 如果需要开始一个新的哈希值，则必须创建一个新的哈希器。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::hash_map::DefaultHasher;
    /// use std::hash::Hasher;
    ///
    /// let mut hasher = DefaultHasher::new();
    /// hasher.write(b"Cool!");
    ///
    /// println!("Hash is {:x}!", hasher.finish());
    /// ```
    ///
    /// [`write`]: Hasher::write
    #[stable(feature = "rust1", since = "1.0.0")]
    fn finish(&self) -> u64;

    /// 将一些数据写入此 `Hasher`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::hash_map::DefaultHasher;
    /// use std::hash::Hasher;
    ///
    /// let mut hasher = DefaultHasher::new();
    /// let data = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef];
    ///
    /// hasher.write(&data);
    ///
    /// println!("Hash is {:x}!", hasher.finish());
    /// ```
    ///
    /// # 给实现者的注意事项
    ///
    /// 您通常不应该将长度前缀作为实现此方法的一部分。
    /// 在需要它的序列之前调用 [`Hasher::write_length_prefix`] 取决于 [`Hash`] 实现。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn write(&mut self, bytes: &[u8]);

    /// 将单个 `u8` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_u8(&mut self, i: u8) {
        self.write(&[i])
    }
    /// 将单个 `u16` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_u16(&mut self, i: u16) {
        self.write(&i.to_ne_bytes())
    }
    /// 将单个 `u32` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_u32(&mut self, i: u32) {
        self.write(&i.to_ne_bytes())
    }
    /// 将单个 `u64` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_u64(&mut self, i: u64) {
        self.write(&i.to_ne_bytes())
    }
    /// 将单个 `u128` 写入此哈希器。
    #[inline]
    #[stable(feature = "i128", since = "1.26.0")]
    fn write_u128(&mut self, i: u128) {
        self.write(&i.to_ne_bytes())
    }
    /// 将单个 `usize` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_usize(&mut self, i: usize) {
        self.write(&i.to_ne_bytes())
    }

    /// 将单个 `i8` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_i8(&mut self, i: i8) {
        self.write_u8(i as u8)
    }
    /// 将单个 `i16` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_i16(&mut self, i: i16) {
        self.write_u16(i as u16)
    }
    /// 将单个 `i32` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_i32(&mut self, i: i32) {
        self.write_u32(i as u32)
    }
    /// 将单个 `i64` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_i64(&mut self, i: i64) {
        self.write_u64(i as u64)
    }
    /// 将单个 `i128` 写入此哈希器。
    #[inline]
    #[stable(feature = "i128", since = "1.26.0")]
    fn write_i128(&mut self, i: i128) {
        self.write_u128(i as u128)
    }
    /// 将单个 `isize` 写入此哈希器。
    #[inline]
    #[stable(feature = "hasher_write", since = "1.3.0")]
    fn write_isize(&mut self, i: isize) {
        self.write_usize(i as usize)
    }

    /// 将长度前缀写入此哈希器，作为无前缀的一部分。
    ///
    /// 如果您正在为自定义集合实现 [`Hash`]，请在将其内容写入此 `Hasher` 之前调用 this。
    /// 这样 `(collection![1, 2, 3], collection![4, 5])` 和 `(collection![1, 2], collection![3, 4, 5])` 将为 `Hasher` 提供不同的值序列
    ///
    /// `impl<T> Hash for [T]` 包含对该方法的调用，因此如果您通过其 `Hash::hash` 方法对切片 (或数组或 vector) 进行哈希处理，您不应该 ** 自己调用 this。
    ///
    /// 此方法仅用于提供域分离。
    /// 如果您想对表示 *data* 的一部分的 `usize` 进行散列处理，那么将其传递给 [`Hasher::write_usize`] 而不是此方法很重要。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(hasher_prefixfree_extras)]
    /// # // 使下面的 `impl` 通过编译器的存根
    /// # struct MyCollection<T>(Option<T>);
    /// # impl<T> MyCollection<T> {
    /// #     fn len(&self) -> usize { todo!() }
    /// # }
    /// # impl<'a, T> IntoIterator for &'a MyCollection<T> {
    /// #     type Item = T;
    /// #     type IntoIter = std::iter::Empty<T>;
    /// #     fn into_iter(self) -> Self::IntoIter { todo!() }
    /// # }
    ///
    /// use std::hash::{Hash, Hasher};
    /// impl<T: Hash> Hash for MyCollection<T> {
    ///     fn hash<H: Hasher>(&self, state: &mut H) {
    ///         state.write_length_prefix(self.len());
    ///         for elt in self {
    ///             elt.hash(state);
    ///         }
    ///     }
    /// }
    /// ```
    ///
    /// # 给实现者的注意事项
    ///
    /// 如果您确定您的 `Hasher` 愿意受到 Hash-DoS 攻击，那么您可以考虑跳过以提高性能为名提供的部分或全部 `len` 的散列。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[inline]
    #[unstable(feature = "hasher_prefixfree_extras", issue = "96762")]
    fn write_length_prefix(&mut self, len: usize) {
        self.write_usize(len);
    }

    /// 将单个 `str` 写入此哈希器。
    ///
    /// 如果您正在实现 [`Hash`]，您通常不需要像 `impl Hash for str` 那样调用 this，所以您应该更喜欢它。
    ///
    /// 这包括前缀自由的域分隔符，所以在调用它之前您不应该 ** 调用 `Self::write_length_prefix`。
    ///
    /// # 给实现者的注意事项
    ///
    /// 至少有两种合理的默认方式来实现这一点。
    /// 哪一个将是默认值尚未确定，所以现在您可能想要专门覆盖它。
    ///
    /// ## 一般答案
    ///
    /// 使用长度前缀来实现它总是正确的:
    ///
    /// ```
    /// # #![feature(hasher_prefixfree_extras)]
    /// # struct Foo;
    /// # impl std::hash::Hasher for Foo {
    /// # fn finish(&self) -> u64 { unimplemented!() }
    /// # fn write(&mut self, _bytes: &[u8]) { unimplemented!() }
    /// fn write_str(&mut self, s: &str) {
    ///     self.write_length_prefix(s.len());
    ///     self.write(s.as_bytes());
    /// }
    /// # }
    /// ```
    ///
    /// 而且，如果您的 `Hasher` 在 `usize` 块中工作，这可能是一种非常有效的方法，因为任何更复杂的事情最终都可能比仅以长度运行一轮更慢。
    ///
    /// ## 如果您的 `Hasher` 按字节工作
    ///
    /// `str` 是 UTF-8 的一个好处是 `b'\xFF'` 字节永远不会发生。这意味着您可以将其，追加，到被散列的字节流并保持前缀自由:
    ///
    /// ```
    /// # #![feature(hasher_prefixfree_extras)]
    /// # struct Foo;
    /// # impl std::hash::Hasher for Foo {
    /// # fn finish(&self) -> u64 { unimplemented!() }
    /// # fn write(&mut self, _bytes: &[u8]) { unimplemented!() }
    /// fn write_str(&mut self, s: &str) {
    ///     self.write(s.as_bytes());
    ///     self.write_u8(0xff);
    /// }
    /// # }
    /// ```
    ///
    /// 这确实要求您的实现不添加额外的填充，因此通常需要您维护一个缓冲区，仅在该缓冲区已满 (或调用 `finish`) 时运行一轮。
    ///
    /// 那是因为如果 `write` 将数据填充到固定的块大小，它很可能会以这样的方式进行，即 `"a"` 和 `"a\x00"` 最终会散列相同的事物序列，从而引入冲突。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[inline]
    #[unstable(feature = "hasher_prefixfree_extras", issue = "96762")]
    fn write_str(&mut self, s: &str) {
        self.write(s.as_bytes());
        self.write_u8(0xff);
    }
}

#[stable(feature = "indirect_hasher_impl", since = "1.22.0")]
impl<H: Hasher + ?Sized> Hasher for &mut H {
    fn finish(&self) -> u64 {
        (**self).finish()
    }
    fn write(&mut self, bytes: &[u8]) {
        (**self).write(bytes)
    }
    fn write_u8(&mut self, i: u8) {
        (**self).write_u8(i)
    }
    fn write_u16(&mut self, i: u16) {
        (**self).write_u16(i)
    }
    fn write_u32(&mut self, i: u32) {
        (**self).write_u32(i)
    }
    fn write_u64(&mut self, i: u64) {
        (**self).write_u64(i)
    }
    fn write_u128(&mut self, i: u128) {
        (**self).write_u128(i)
    }
    fn write_usize(&mut self, i: usize) {
        (**self).write_usize(i)
    }
    fn write_i8(&mut self, i: i8) {
        (**self).write_i8(i)
    }
    fn write_i16(&mut self, i: i16) {
        (**self).write_i16(i)
    }
    fn write_i32(&mut self, i: i32) {
        (**self).write_i32(i)
    }
    fn write_i64(&mut self, i: i64) {
        (**self).write_i64(i)
    }
    fn write_i128(&mut self, i: i128) {
        (**self).write_i128(i)
    }
    fn write_isize(&mut self, i: isize) {
        (**self).write_isize(i)
    }
    fn write_length_prefix(&mut self, len: usize) {
        (**self).write_length_prefix(len)
    }
    fn write_str(&mut self, s: &str) {
        (**self).write_str(s)
    }
}

/// 用于创建 [`Hasher`] 实例的 trait。
///
/// `BuildHasher` 通常用于 (例如，由 [`HashMap`] 来) 为每个键创建 [`Hasher`]，使得它们彼此独立地进行哈希处理，因为 [`Hasher`] 包含状态。
///
///
/// 对于 `BuildHasher` 的每个实例，由 [`build_hasher`] 创建的 [`Hasher`] 应该相同。
/// 也就是说，如果将相同的字节流馈送到每个哈希器中，则还将生成相同的输出。
///
/// # Examples
///
/// ```
/// use std::collections::hash_map::RandomState;
/// use std::hash::{BuildHasher, Hasher};
///
/// let s = RandomState::new();
/// let mut hasher_1 = s.build_hasher();
/// let mut hasher_2 = s.build_hasher();
///
/// hasher_1.write_u32(8128);
/// hasher_2.write_u32(8128);
///
/// assert_eq!(hasher_1.finish(), hasher_2.finish());
/// ```
///
/// [`build_hasher`]: BuildHasher::build_hasher
/// [`HashMap`]: ../../std/collections/struct.HashMap.html
///
///
#[stable(since = "1.7.0", feature = "build_hasher")]
pub trait BuildHasher {
    /// 将创建的哈希器的类型。
    #[stable(since = "1.7.0", feature = "build_hasher")]
    type Hasher: Hasher;

    /// 创建一个新的哈希器。
    ///
    /// 在同一实例上对 `build_hasher` 的每次调用都应产生相同的 [`Hasher`]。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::hash_map::RandomState;
    /// use std::hash::BuildHasher;
    ///
    /// let s = RandomState::new();
    /// let new_s = s.build_hasher();
    /// ```
    #[stable(since = "1.7.0", feature = "build_hasher")]
    fn build_hasher(&self) -> Self::Hasher;

    /// 计算单个值的哈希值。
    ///
    /// 这是为了方便*消耗*哈希的代码，例如哈希表的实现或在单元测试中检查自定义 [`Hash`] 实现是否按预期运行。
    ///
    ///
    /// 这不能用在任何*创建*哈希的代码中，例如在 [`Hash`] 的实现中。
    /// 创建多个值的组合哈希的方法是使用同一个 [`Hasher`] 多次调用 [`Hash::hash`]，而不是重复调用此方法并组合结果。
    ///
    /// # Example
    ///
    /// ```
    /// use std::cmp::{max, min};
    /// use std::hash::{BuildHasher, Hash, Hasher};
    /// struct OrderAmbivalentPair<T: Ord>(T, T);
    /// impl<T: Ord + Hash> Hash for OrderAmbivalentPair<T> {
    ///     fn hash<H: Hasher>(&self, hasher: &mut H) {
    ///         min(&self.0, &self.1).hash(hasher);
    ///         max(&self.0, &self.1).hash(hasher);
    ///     }
    /// }
    ///
    /// // 然后，在 `#[test]` 类型中...
    /// let bh = std::collections::hash_map::RandomState::new();
    /// assert_eq!(
    ///     bh.hash_one(OrderAmbivalentPair(1, 2)),
    ///     bh.hash_one(OrderAmbivalentPair(2, 1))
    /// );
    /// assert_eq!(
    ///     bh.hash_one(OrderAmbivalentPair(10, 2)),
    ///     bh.hash_one(&OrderAmbivalentPair(2, 10))
    /// );
    /// ```
    ///
    ///
    ///
    #[stable(feature = "build_hasher_simple_hash_one", since = "1.71.0")]
    fn hash_one<T: Hash>(&self, x: T) -> u64
    where
        Self: Sized,
        Self::Hasher: Hasher,
    {
        let mut hasher = self.build_hasher();
        x.hash(&mut hasher);
        hasher.finish()
    }
}

/// 用于为实现 [`Hasher`] 和 [`Default`] 的类型创建默认的 [`BuildHasher`] 实例。
///
/// `BuildHasherDefault<H>` 可以在类型 `H` 实现 [`Hasher`] 和 [`Default`] 时使用，并且您需要相应的 [`BuildHasher`] 实例，但没有定义。
///
///
/// 任何 `BuildHasherDefault` 都是 [零大小][zero-sized]。可以用 [`default`][method.default] 创建。
/// 当将 `BuildHasherDefault` 与 [`HashMap`] 或 [`HashSet`] 一起使用时，不需要这样做，因为它们自己实现了适当的 [`Default`] 实例。
///
/// # Examples
///
/// 使用 `BuildHasherDefault` 指定用于的自定义 [`BuildHasher`]
/// [`HashMap`]:
///
/// ```
/// use std::collections::HashMap;
/// use std::hash::{BuildHasherDefault, Hasher};
///
/// #[derive(Default)]
/// struct MyHasher;
///
/// impl Hasher for MyHasher {
///     fn write(&mut self, bytes: &[u8]) {
///         // 您的哈希算法就在这里！
///        unimplemented!()
///     }
///
///     fn finish(&self) -> u64 {
///         // 您的哈希算法就在这里！
///         unimplemented!()
///     }
/// }
///
/// type MyBuildHasher = BuildHasherDefault<MyHasher>;
///
/// let hash_map = HashMap::<u32, u32, MyBuildHasher>::default();
/// ```
///
/// [method.default]: BuildHasherDefault::default
/// [`HashMap`]: ../../std/collections/struct.HashMap.html
/// [`HashSet`]: ../../std/collections/struct.HashSet.html
/// [zero-sized]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts
///
///
///
///
#[stable(since = "1.7.0", feature = "build_hasher")]
pub struct BuildHasherDefault<H>(marker::PhantomData<fn() -> H>);

#[stable(since = "1.9.0", feature = "core_impl_debug")]
impl<H> fmt::Debug for BuildHasherDefault<H> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("BuildHasherDefault").finish()
    }
}

#[stable(since = "1.7.0", feature = "build_hasher")]
impl<H: Default + Hasher> BuildHasher for BuildHasherDefault<H> {
    type Hasher = H;

    fn build_hasher(&self) -> H {
        H::default()
    }
}

#[stable(since = "1.7.0", feature = "build_hasher")]
impl<H> Clone for BuildHasherDefault<H> {
    fn clone(&self) -> BuildHasherDefault<H> {
        BuildHasherDefault(marker::PhantomData)
    }
}

#[stable(since = "1.7.0", feature = "build_hasher")]
impl<H> Default for BuildHasherDefault<H> {
    fn default() -> BuildHasherDefault<H> {
        BuildHasherDefault(marker::PhantomData)
    }
}

#[stable(since = "1.29.0", feature = "build_hasher_eq")]
impl<H> PartialEq for BuildHasherDefault<H> {
    fn eq(&self, _other: &BuildHasherDefault<H>) -> bool {
        true
    }
}

#[stable(since = "1.29.0", feature = "build_hasher_eq")]
impl<H> Eq for BuildHasherDefault<H> {}

mod impls {
    use crate::mem;
    use crate::slice;

    use super::*;

    macro_rules! impl_write {
        ($(($ty:ident, $meth:ident),)*) => {$(
            #[stable(feature = "rust1", since = "1.0.0")]
            impl Hash for $ty {
                #[inline]
                fn hash<H: Hasher>(&self, state: &mut H) {
                    state.$meth(*self)
                }

                #[inline]
                fn hash_slice<H: Hasher>(data: &[$ty], state: &mut H) {
                    let newlen = mem::size_of_val(data);
                    let ptr = data.as_ptr() as *const u8;
                    // SAFETY: `ptr` 有效且已对齐，因为此宏仅用于没有填充的数字原语。
                    // 新切片仅跨越 `data`，并且不会发生可变的，并且其总大小与原始 `data` 相同，因此不能超过 `isize::MAX`。
                    //
                    //
                    state.write(unsafe { slice::from_raw_parts(ptr, newlen) })
                }
            }
        )*}
    }

    impl_write! {
        (u8, write_u8),
        (u16, write_u16),
        (u32, write_u32),
        (u64, write_u64),
        (usize, write_usize),
        (i8, write_i8),
        (i16, write_i16),
        (i32, write_i32),
        (i64, write_i64),
        (isize, write_isize),
        (u128, write_u128),
        (i128, write_i128),
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl Hash for bool {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            state.write_u8(*self as u8)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl Hash for char {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            state.write_u32(*self as u32)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl Hash for str {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            state.write_str(self);
        }
    }

    #[stable(feature = "never_hash", since = "1.29.0")]
    impl Hash for ! {
        #[inline]
        fn hash<H: Hasher>(&self, _: &mut H) {
            *self
        }
    }

    macro_rules! impl_hash_tuple {
        () => (
            #[stable(feature = "rust1", since = "1.0.0")]
            impl Hash for () {
                #[inline]
                fn hash<H: Hasher>(&self, _state: &mut H) {}
            }
        );

        ( $($name:ident)+) => (
            maybe_tuple_doc! {
                $($name)+ @
                #[stable(feature = "rust1", since = "1.0.0")]
                impl<$($name: Hash),+> Hash for ($($name,)+) where last_type!($($name,)+): ?Sized {
                    #[allow(non_snake_case)]
                    #[inline]
                    fn hash<S: Hasher>(&self, state: &mut S) {
                        let ($(ref $name,)+) = *self;
                        $($name.hash(state);)+
                    }
                }
            }
        );
    }

    macro_rules! maybe_tuple_doc {
        ($a:ident @ #[$meta:meta] $item:item) => {
            #[doc(fake_variadic)]
            #[doc = "This trait is implemented for tuples up to twelve items long."]
            #[$meta]
            $item
        };
        ($a:ident $($rest_a:ident)+ @ #[$meta:meta] $item:item) => {
            #[doc(hidden)]
            #[$meta]
            $item
        };
    }

    macro_rules! last_type {
        ($a:ident,) => { $a };
        ($a:ident, $($rest_a:ident,)+) => { last_type!($($rest_a,)+) };
    }

    impl_hash_tuple! {}
    impl_hash_tuple! { T }
    impl_hash_tuple! { T B }
    impl_hash_tuple! { T B C }
    impl_hash_tuple! { T B C D }
    impl_hash_tuple! { T B C D E }
    impl_hash_tuple! { T B C D E F }
    impl_hash_tuple! { T B C D E F G }
    impl_hash_tuple! { T B C D E F G H }
    impl_hash_tuple! { T B C D E F G H I }
    impl_hash_tuple! { T B C D E F G H I J }
    impl_hash_tuple! { T B C D E F G H I J K }
    impl_hash_tuple! { T B C D E F G H I J K L }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: Hash> Hash for [T] {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            state.write_length_prefix(self.len());
            Hash::hash_slice(self, state)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized + Hash> Hash for &T {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            (**self).hash(state);
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized + Hash> Hash for &mut T {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            (**self).hash(state);
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Hash for *const T {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            let (address, metadata) = self.to_raw_parts();
            state.write_usize(address.addr());
            metadata.hash(state);
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Hash for *mut T {
        #[inline]
        fn hash<H: Hasher>(&self, state: &mut H) {
            let (address, metadata) = self.to_raw_parts();
            state.write_usize(address.addr());
            metadata.hash(state);
        }
    }
}