11//! Stable hasher adapted for cross-platform independent hash.
22
3- use crate :: sip128:: SipHasher128 ;
4-
53use std:: fmt;
64use std:: hash:: Hasher ;
75
86#[ cfg( test) ]
97mod tests;
108
9+ /// Extended the [`Hasher`] trait for use with [`StableHasher`].
10+ ///
11+ /// It permits returning an arbitrary type as the [`Self::Hash`] type
12+ /// contrary to the [`Hasher`] trait which can only return `u64`. This
13+ /// is useful when the hasher uses a different representation.
14+ ///
15+ /// # Example
16+ ///
17+ /// ```
18+ /// use std::hash::Hasher;
19+ /// use rustc_stable_hash::ExtendedHasher;
20+ ///
21+ /// struct DumbHasher(u128);
22+ ///
23+ /// impl Hasher for DumbHasher {
24+ /// fn write(&mut self, a: &[u8]) {
25+ /// # self.0 = a.iter().fold(0u128, |acc, a| acc + (*a as u128)) + self.0;
26+ /// // ...
27+ /// }
28+ ///
29+ /// fn finish(&self) -> u64 {
30+ /// self.0 as u64 // really dumb
31+ /// }
32+ /// }
33+ ///
34+ /// impl ExtendedHasher for DumbHasher {
35+ /// type Hash = u128;
36+ ///
37+ /// fn short_write<const LEN: usize>(&mut self, bytes: [u8; LEN]) {
38+ /// self.write(&bytes)
39+ /// }
40+ ///
41+ /// fn finish(self) -> Self::Hash {
42+ /// self.0
43+ /// }
44+ /// }
45+ /// ```
46+ pub trait ExtendedHasher : Hasher {
47+ /// Type returned by the hasher.
48+ type Hash ;
49+
50+ /// Optimized version of [`Hasher::write`] but for small write.
51+ fn short_write < const LEN : usize > ( & mut self , bytes : [ u8 ; LEN ] ) ;
52+
53+ /// Finalization method of the hasher to return the [`Hash`].
54+ fn finish ( self ) -> Self :: Hash ;
55+ }
56+
1157/// A Stable Hasher adapted for cross-platform independent hash.
1258///
1359/// When hashing something that ends up affecting properties like symbol names,
@@ -21,24 +67,26 @@ mod tests;
2167/// # Example
2268///
2369/// ```
24- /// use rustc_stable_hash::{StableHasher, StableHasherResult};
70+ /// use rustc_stable_hash::{StableHasher, StableHasherResult, StableSipHasher128 };
2571/// use std::hash::Hasher;
2672///
2773/// struct Hash128([u64; 2]);
2874/// impl StableHasherResult for Hash128 {
75+ /// type Hash = [u64; 2];
76+ ///
2977/// fn finish(hash: [u64; 2]) -> Hash128 {
3078/// Hash128(hash)
3179/// }
3280/// }
3381///
34- /// let mut hasher = StableHasher ::new();
82+ /// let mut hasher = StableSipHasher128 ::new();
3583/// hasher.write_usize(0xFA);
3684///
3785/// let hash: Hash128 = hasher.finish();
3886/// ```
3987#[ must_use]
40- pub struct StableHasher {
41- state : SipHasher128 ,
88+ pub struct StableHasher < H : ExtendedHasher > {
89+ state : H ,
4290}
4391
4492/// Trait for retrieving the result of the stable hashing operation.
@@ -51,6 +99,8 @@ pub struct StableHasher {
5199/// struct Hash128(u128);
52100///
53101/// impl StableHasherResult for Hash128 {
102+ /// type Hash = [u64; 2];
103+ ///
54104/// fn finish(hash: [u64; 2]) -> Hash128 {
55105/// let upper: u128 = hash[0] as u128;
56106/// let lower: u128 = hash[1] as u128;
@@ -60,23 +110,36 @@ pub struct StableHasher {
60110/// }
61111/// ```
62112pub trait StableHasherResult : Sized {
113+ type Hash ;
114+
63115 /// Retrieving the finalized state of the [`StableHasher`] and construct
64116/// an [`Self`] containing the hash.
65- fn finish ( hasher : [ u64 ; 2 ] ) -> Self ;
117+ fn finish ( hash : Self :: Hash ) -> Self ;
66118}
67119
68- impl StableHasher {
120+ impl < H : ExtendedHasher + Default > StableHasher < H > {
69121 /// Creates a new [`StableHasher`].
70122///
71123/// To be used with the [`Hasher`] implementation and [`StableHasher::finish`].
124+ // TODO: Should this exist as is? or maybe it should take an `ExtendedHasher` as input?
72125 #[ inline]
73126 #[ must_use]
74127 pub fn new ( ) -> Self {
128+ Default :: default ( )
129+ }
130+ }
131+
132+ impl < H : ExtendedHasher + Default > Default for StableHasher < H > {
133+ #[ inline]
134+ #[ must_use]
135+ fn default ( ) -> Self {
75136 StableHasher {
76- state : SipHasher128 :: new_with_keys ( 0 , 0 ) ,
137+ state : Default :: default ( ) ,
77138 }
78139 }
140+ }
79141
142+ impl < H : ExtendedHasher > StableHasher < H > {
80143 /// Returns the typed-hash value for the values written.
81144///
82145/// The resulting typed-hash value is constructed from an
@@ -85,23 +148,23 @@ impl StableHasher {
85148/// To be used in-place of [`Hasher::finish`].
86149#[ inline]
87150 #[ must_use]
88- pub fn finish < W : StableHasherResult > ( self ) -> W {
89- W :: finish ( self . state . finish128 ( ) )
151+ pub fn finish < W : StableHasherResult < Hash = H :: Hash > > ( self ) -> W {
152+ W :: finish ( self . state . finish ( ) )
90153 }
91154}
92155
93- impl fmt:: Debug for StableHasher {
156+ impl < H : ExtendedHasher + fmt:: Debug > fmt :: Debug for StableHasher < H > {
94157 fn fmt ( & self , f : & mut fmt:: Formatter < ' _ > ) -> fmt:: Result {
95158 write ! ( f, "{:?}" , self . state)
96159 }
97160}
98161
99- impl Hasher for StableHasher {
162+ impl < H : ExtendedHasher > Hasher for StableHasher < H > {
100163 /// Returns a combined hash.
101164///
102165/// For greater precision use instead [`StableHasher::finish`].
103166fn finish ( & self ) -> u64 {
104- self . state . finish ( )
167+ Hasher :: finish ( & self . state )
105168 }
106169
107170 #[ inline]
@@ -192,7 +255,7 @@ impl Hasher for StableHasher {
192255 // Cold path
193256 #[ cold]
194257 #[ inline( never) ]
195- fn hash_value ( state : & mut SipHasher128 , value : u64 ) {
258+ fn hash_value < H : ExtendedHasher > ( state : & mut H , value : u64 ) {
196259 state. write_u8 ( 0xFF ) ;
197260 state. short_write ( value. to_le_bytes ( ) ) ;
198261 }
0 commit comments