crc32fast/
lib.rs

1//! Fast, SIMD-accelerated CRC32 (IEEE) checksum computation.
2//!
3//! ## Usage
4//!
5//! ### Simple usage
6//!
7//! For simple use-cases, you can call the [`hash()`] convenience function to
8//! directly compute the CRC32 checksum for a given byte slice:
9//!
10//! ```rust
11//! let checksum = crc32fast::hash(b"foo bar baz");
12//! ```
13//!
14//! ### Advanced usage
15//!
16//! For use-cases that require more flexibility or performance, for example when
17//! processing large amounts of data, you can create and manipulate a [`Hasher`]:
18//!
19//! ```rust
20//! use crc32fast::Hasher;
21//!
22//! let mut hasher = Hasher::new();
23//! hasher.update(b"foo bar baz");
24//! let checksum = hasher.finalize();
25//! ```
26//!
27//! ## Performance
28//!
29//! This crate contains multiple CRC32 implementations:
30//!
31//! - A fast baseline implementation which processes up to 16 bytes per iteration
32//! - An optimized implementation for modern `x86` using `sse` and `pclmulqdq` instructions
33//!
34//! Calling the [`Hasher::new`] constructor at runtime will perform a feature detection to select the most
35//! optimal implementation for the current CPU feature set.
36
37#![cfg_attr(not(feature = "std"), no_std)]
38
39// #[deny(missing_docs)]
40// #[cfg(test)]
41// #[macro_use]
42// extern crate quickcheck;
43
44// #[macro_use]
45// extern crate cfg_if;
46
47use core::{fmt, hash};
48#[cfg(feature = "std")]
49use std as core;
50
51mod baseline;
52mod combine;
53mod specialized;
54mod table;
55
56/// Computes the CRC32 hash of a byte slice.
57///
58/// Check out [`Hasher`] for more advanced use-cases.
59pub fn hash(buf: &[u8]) -> u32 {
60    let mut h = Hasher::new();
61    h.update(buf);
62    h.finalize()
63}
64
65#[derive(Clone)]
66enum State {
67    Baseline(baseline::State),
68    Specialized(specialized::State),
69}
70
71#[derive(Clone)]
72/// Represents an in-progress CRC32 computation.
73pub struct Hasher {
74    amount: u64,
75    state: State,
76}
77
78const DEFAULT_INIT_STATE: u32 = 0;
79
80impl Hasher {
81    /// Create a new `Hasher`.
82    ///
83    /// This will perform a CPU feature detection at runtime to select the most
84    /// optimal implementation for the current processor architecture.
85    pub fn new() -> Self {
86        Self::new_with_initial(DEFAULT_INIT_STATE)
87    }
88
89    /// Create a new `Hasher` with an initial CRC32 state.
90    ///
91    /// This works just like `Hasher::new`, except that it allows for an initial
92    /// CRC32 state to be passed in.
93    pub fn new_with_initial(init: u32) -> Self {
94        Self::new_with_initial_len(init, 0)
95    }
96
97    /// Create a new `Hasher` with an initial CRC32 state.
98    ///
99    /// As `new_with_initial`, but also accepts a length (in bytes). The
100    /// resulting object can then be used with `combine` to compute `crc(a ||
101    /// b)` from `crc(a)`, `crc(b)`, and `len(b)`.
102    pub fn new_with_initial_len(init: u32, amount: u64) -> Self {
103        Self::internal_new_specialized(init, amount).unwrap_or_else(|| Self::internal_new_baseline(init, amount))
104    }
105
106    #[doc(hidden)]
107    // Internal-only API. Don't use.
108    pub fn internal_new_baseline(init: u32, amount: u64) -> Self {
109        Hasher {
110            amount,
111            state: State::Baseline(baseline::State::new(init)),
112        }
113    }
114
115    #[doc(hidden)]
116    // Internal-only API. Don't use.
117    pub fn internal_new_specialized(init: u32, amount: u64) -> Option<Self> {
118        {
119            if let Some(state) = specialized::State::new(init) {
120                return Some(Hasher {
121                    amount,
122                    state: State::Specialized(state),
123                });
124            }
125        }
126        None
127    }
128
129    /// Process the given byte slice and update the hash state.
130    pub fn update(&mut self, buf: &[u8]) {
131        self.amount += buf.len() as u64;
132        match self.state {
133            State::Baseline(ref mut state) => state.update(buf),
134            State::Specialized(ref mut state) => state.update(buf),
135        }
136    }
137
138    /// Finalize the hash state and return the computed CRC32 value.
139    pub fn finalize(self) -> u32 {
140        match self.state {
141            State::Baseline(state) => state.finalize(),
142            State::Specialized(state) => state.finalize(),
143        }
144    }
145
146    /// Reset the hash state.
147    pub fn reset(&mut self) {
148        self.amount = 0;
149        match self.state {
150            State::Baseline(ref mut state) => state.reset(),
151            State::Specialized(ref mut state) => state.reset(),
152        }
153    }
154
155    /// Combine the hash state with the hash state for the subsequent block of bytes.
156    pub fn combine(&mut self, other: &Self) {
157        self.amount += other.amount;
158        let other_crc = other.clone().finalize();
159        match self.state {
160            State::Baseline(ref mut state) => state.combine(other_crc, other.amount),
161            State::Specialized(ref mut state) => state.combine(other_crc, other.amount),
162        }
163    }
164}
165
166impl fmt::Debug for Hasher {
167    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
168        f.debug_struct("crc32fast::Hasher").finish()
169    }
170}
171
172impl Default for Hasher {
173    fn default() -> Self {
174        Self::new()
175    }
176}
177
178impl hash::Hasher for Hasher {
179    fn write(&mut self, bytes: &[u8]) {
180        self.update(bytes)
181    }
182
183    fn finish(&self) -> u64 {
184        u64::from(self.clone().finalize())
185    }
186}
187
188#[cfg(test)]
189mod test {
190    use rand::{TryRngCore, rngs::OsRng};
191
192    use super::Hasher;
193
194    #[test]
195    fn combine() {
196        let mut rand_generator = OsRng {};
197
198        let mut bytes_1 = vec![100];
199        rand_generator.try_fill_bytes(&mut bytes_1).unwrap();
200
201        let mut bytes_2 = vec![200];
202        rand_generator.try_fill_bytes(&mut bytes_2).unwrap();
203
204        let mut hash_a = Hasher::new();
205        hash_a.update(&bytes_1);
206        hash_a.update(&bytes_2);
207        let mut hash_b = Hasher::new();
208        hash_b.update(&bytes_2);
209        let mut hash_c = Hasher::new();
210        hash_c.update(&bytes_1);
211        hash_c.combine(&hash_b);
212
213        assert_eq!(hash_a.finalize(), hash_c.finalize());
214    }
215
216    #[test]
217    fn combine_from_len() {
218        let mut rand_generator = OsRng {};
219
220        let mut bytes_1 = vec![200];
221        rand_generator.try_fill_bytes(&mut bytes_1).unwrap();
222
223        let mut bytes_2 = vec![100];
224        rand_generator.try_fill_bytes(&mut bytes_2).unwrap();
225
226        let mut hash_a = Hasher::new();
227        hash_a.update(&bytes_1);
228        let a = hash_a.finalize();
229
230        let mut hash_b = Hasher::new();
231        hash_b.update(&bytes_2);
232        let b = hash_b.finalize();
233
234        let mut hash_ab = Hasher::new();
235        hash_ab.update(&bytes_1);
236        hash_ab.update(&bytes_2);
237        let ab = hash_ab.finalize();
238
239        let mut reconstructed = Hasher::new_with_initial_len(a, bytes_1.len() as u64);
240        let hash_b_reconstructed = Hasher::new_with_initial_len(b, bytes_2.len() as u64);
241
242        reconstructed.combine(&hash_b_reconstructed);
243
244        assert_eq!(reconstructed.finalize(), ab);
245    }
246}
crc32fast/lib.rs

crc32fast/
lib.rs
