bufhash 0.1.1

Buffered hashing facilities
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

//! Partitioned hashers.
//!
//! See the [crate documentation](../index.html) for more details.

mod hasher;

pub use hasher::Hasher;

/// A wrapper around a [partitioned hasher](crate::partitioned::Hasher) that implements
/// [`std::hash::Hasher`].
///
/// See the [crate documentation](../index.html) for more details.
#[derive(Clone, Debug)]
pub struct PartitionedHasher<const N: usize, H: Hasher<N>> {
    hasher: H,
    buffer: Vec<u8>,
}

impl<const N: usize, H: Hasher<N>> PartitionedHasher<N, H> {
    /// Creates a new [`PartitionedHasher`].
    ///
    /// # Examples
    ///
    /// ```
    /// use std::hash::Hasher as _;
    ///
    /// use bufhash::partitioned::Hasher;
    /// use bufhash::PartitionedHasher;
    ///
    /// #[derive(Debug, Default)]
    /// pub struct Simple(u64);
    ///
    /// impl Hasher<8> for Simple {
    ///     fn write(&mut self, bytes: &[u8; 8]) {
    ///         let data = u64::from_le_bytes(*bytes);
    ///         self.0 = self.0.wrapping_add(data);
    ///     }
    ///
    ///     fn finish(&self, bytes: &[u8]) -> u64 {
    ///         self.0 << bytes.len()
    ///     }
    /// }
    ///
    ///
    /// let mut hasher = PartitionedHasher::new(Simple::default());
    /// hasher.write(b"Hello, world!");
    /// assert_eq!(hasher.finish(), 0xE405_8DED_8D8C_A900);
    /// ```
    pub fn new(hasher: H) -> Self {
        Self {
            hasher,
            buffer: Vec::with_capacity(N),
        }
    }

    #[cfg(test)]
    pub fn inner_vec(&self) -> &Vec<u8> {
        &self.buffer
    }
}

impl<const N: usize, H: Hasher<N>> std::default::Default for PartitionedHasher<N, H>
where
    H: std::default::Default,
{
    fn default() -> Self {
        Self {
            hasher: Default::default(),
            buffer: Vec::with_capacity(N),
        }
    }
}

impl<const N: usize, H: Hasher<N>> core::hash::Hasher for PartitionedHasher<N, H> {
    fn write(&mut self, bytes: &[u8]) {
        let mut bytes = bytes;

        // (1) Checks the buffer to see if any bytes are waiting to be processed. If
        // they are, attempt to process them.
        if !self.buffer.is_empty() {
            let needed = N - self.buffer.len();
            let borrowed = bytes.get(..needed).unwrap_or(bytes);

            self.buffer.extend_from_slice(borrowed);

            // Not enough elements to fill up the buffer, so just return (as the new
            // elements were just added to [`self.buffer`]).
            if self.buffer.len() != N {
                return;
            }

            let mut buffer = [0u8; N];
            buffer.copy_from_slice(&self.buffer[..N]);
            self.hasher.write(&buffer);
            self.buffer.clear();

            // Advance the bytes pointer by the number of elements we consumed to
            // complete the buffer.
            bytes = &bytes[borrowed.len()..]
        }

        // (2) Consume as many of the bytes as is possible.
        while bytes.len() >= N {
            let (chunk, remaining) = bytes.split_at(N);
            // SAFETY: we just ensured that bytes has at least N elements and that
            // `chunk` was split exactly at N elements. As such, this cast will always
            // unwrap.
            self.hasher.write(chunk.try_into().unwrap());
            bytes = remaining;
        }

        // (3) If there are remaining bytes, add them, to the buffer for the next write.
        if !bytes.is_empty() {
            self.buffer.extend_from_slice(bytes);
        }
    }

    fn finish(&self) -> u64 {
        self.hasher.finish(&self.buffer)
    }
}

#[cfg(test)]
mod tests {
    use std::hash::Hasher as _;

    use super::*;

    #[derive(Debug, Default)]
    pub struct Simple(u64);

    impl Hasher<8> for Simple {
        fn write(&mut self, bytes: &[u8; 8]) {
            let data = u64::from_le_bytes(*bytes);
            self.0 = self.0.wrapping_add(data);
        }

        fn finish(&self, bytes: &[u8]) -> u64 {
            self.0 << bytes.len()
        }
    }

    #[test]
    fn it_works_with_single_call() {
        let mut hasher = PartitionedHasher::new(Simple::default());
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 0);

        hasher.write(b"Hello, world!");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 5);

        assert_eq!(hasher.finish(), 0xE405_8DED_8D8C_A900);
    }

    #[test]
    fn it_works_with_multiple_calls() {
        let mut hasher = PartitionedHasher::new(Simple::default());
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 0);

        hasher.write(b"H");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 1);

        hasher.write(b"e");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 2);

        hasher.write(b"l");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 3);

        hasher.write(b"l");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 4);

        hasher.write(b"o");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 5);

        hasher.write(b",");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 6);

        hasher.write(b" ");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 7);

        hasher.write(b"w");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 0);

        hasher.write(b"o");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 1);

        hasher.write(b"r");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 2);

        hasher.write(b"l");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 3);

        hasher.write(b"d");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 4);

        hasher.write(b"!");
        assert_eq!(hasher.inner_vec().capacity(), 8);
        assert_eq!(hasher.inner_vec().len(), 5);

        assert_eq!(hasher.finish(), 0xE405_8DED_8D8C_A900);
    }
}