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}