artichoke_core/
hash.rs

1//! Build hashers and hash values.
2
3use core::hash::BuildHasher;
4
5/// A trait for retrieving an interpreter-global [`BuildHasher`].
6///
7/// The [`BuildHasher`] associated with the interpreter is for creating instances
8/// of [`Hasher`]. A `BuildHasher` is typically used (e.g., by `HashMap`) to
9/// create [`Hasher`]s for each key such that they are hashed independently of
10/// one another, since [`Hasher`]s contain state.
11///
12/// By associating one [`BuildHasher`] with the interpreter, identical Ruby
13/// objects should hash identically, even if the interpreter's [`BuildHasher`]
14/// includes randomness.
15///
16/// [`Hasher`]: core::hash::Hasher
17pub trait Hash {
18    /// Concrete error type for errors encountered when retrieving the
19    /// interpreter's global [`BuildHasher`].
20    type Error;
21
22    /// Concrete [`BuildHasher`] type which is global to the interpreter.
23    type GlobalBuildHasher: BuildHasher;
24
25    /// Retrieve the interpreter's global [`BuildHasher`].
26    ///
27    /// # Errors
28    ///
29    /// If the [`BuildHasher`] is inaccessible, an error is returned.
30    fn global_build_hasher(&mut self) -> Result<&Self::GlobalBuildHasher, Self::Error>;
31}