crc32/
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 = crc32::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 crc32::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
44use core::{fmt, hash};
45#[cfg(feature = "std")]
46use std as core;
47
48mod baseline;
49mod combine;
50mod specialized;
51mod table;
52
53/// Computes the CRC32 hash of a byte slice.
54///
55/// Check out [`Hasher`] for more advanced use-cases.
56pub fn hash(buf: &[u8]) -> u32 {
57    let mut h = Hasher::new();
58    h.update(buf);
59    h.finalize()
60}
61
62#[derive(Clone)]
63enum State {
64    Baseline(baseline::State),
65    Specialized(specialized::State),
66}
67
68#[derive(Clone)]
69/// Represents an in-progress CRC32 computation.
70pub struct Hasher {
71    amount: u64,
72    state: State,
73}
74
75const DEFAULT_INIT_STATE: u32 = 0;
76
77impl Hasher {
78    /// Create a new `Hasher`.
79    ///
80    /// This will perform a CPU feature detection at runtime to select the most
81    /// optimal implementation for the current processor architecture.
82    pub fn new() -> Self {
83        Self::new_with_initial(DEFAULT_INIT_STATE)
84    }
85
86    /// Create a new `Hasher` with an initial CRC32 state.
87    ///
88    /// This works just like `Hasher::new`, except that it allows for an initial
89    /// CRC32 state to be passed in.
90    pub fn new_with_initial(init: u32) -> Self {
91        Self::new_with_initial_len(init, 0)
92    }
93
94    /// Create a new `Hasher` with an initial CRC32 state.
95    ///
96    /// As `new_with_initial`, but also accepts a length (in bytes). The
97    /// resulting object can then be used with `combine` to compute `crc(a ||
98    /// b)` from `crc(a)`, `crc(b)`, and `len(b)`.
99    pub fn new_with_initial_len(init: u32, amount: u64) -> Self {
100        Self::internal_new_specialized(init, amount).unwrap_or_else(|| Self::internal_new_baseline(init, amount))
101    }
102
103    #[doc(hidden)]
104    // Internal-only API. Don't use.
105    pub fn internal_new_baseline(init: u32, amount: u64) -> Self {
106        Hasher {
107            amount,
108            state: State::Baseline(baseline::State::new(init)),
109        }
110    }
111
112    #[doc(hidden)]
113    // Internal-only API. Don't use.
114    pub fn internal_new_specialized(init: u32, amount: u64) -> Option<Self> {
115        {
116            if let Some(state) = specialized::State::new(init) {
117                return Some(Hasher {
118                    amount,
119                    state: State::Specialized(state),
120                });
121            }
122        }
123        None
124    }
125
126    /// Process the given byte slice and update the hash state.
127    pub fn update(&mut self, buf: &[u8]) {
128        self.amount += buf.len() as u64;
129        match self.state {
130            State::Baseline(ref mut state) => state.update(buf),
131            State::Specialized(ref mut state) => state.update(buf),
132        }
133    }
134
135    /// Finalize the hash state and return the computed CRC32 value.
136    pub fn finalize(self) -> u32 {
137        match self.state {
138            State::Baseline(state) => state.finalize(),
139            State::Specialized(state) => state.finalize(),
140        }
141    }
142
143    /// Reset the hash state.
144    pub fn reset(&mut self) {
145        self.amount = 0;
146        match self.state {
147            State::Baseline(ref mut state) => state.reset(),
148            State::Specialized(ref mut state) => state.reset(),
149        }
150    }
151
152    /// Combine the hash state with the hash state for the subsequent block of bytes.
153    pub fn combine(&mut self, other: &Self) {
154        self.amount += other.amount;
155        let other_crc = other.clone().finalize();
156        match self.state {
157            State::Baseline(ref mut state) => state.combine(other_crc, other.amount),
158            State::Specialized(ref mut state) => state.combine(other_crc, other.amount),
159        }
160    }
161}
162
163impl fmt::Debug for Hasher {
164    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
165        f.debug_struct("crc32::Hasher").finish()
166    }
167}
168
169impl Default for Hasher {
170    fn default() -> Self {
171        Self::new()
172    }
173}
174
175impl hash::Hasher for Hasher {
176    fn write(&mut self, bytes: &[u8]) {
177        self.update(bytes)
178    }
179
180    fn finish(&self) -> u64 {
181        u64::from(self.clone().finalize())
182    }
183}
184
185#[cfg(test)]
186mod test {
187    use rand::{TryRng, rngs::SysRng};
188
189    use super::Hasher;
190
191    #[test]
192    fn combine() {
193        let mut rand_generator = SysRng;
194
195        let mut bytes_1 = vec![100];
196        rand_generator.try_fill_bytes(&mut bytes_1).unwrap();
197
198        let mut bytes_2 = vec![200];
199        rand_generator.try_fill_bytes(&mut bytes_2).unwrap();
200
201        let mut hash_a = Hasher::new();
202        hash_a.update(&bytes_1);
203        hash_a.update(&bytes_2);
204        let mut hash_b = Hasher::new();
205        hash_b.update(&bytes_2);
206        let mut hash_c = Hasher::new();
207        hash_c.update(&bytes_1);
208        hash_c.combine(&hash_b);
209
210        assert_eq!(hash_a.finalize(), hash_c.finalize());
211    }
212
213    #[test]
214    fn combine_from_len() {
215        let mut rand_generator = SysRng;
216
217        let mut bytes_1 = vec![200];
218        rand_generator.try_fill_bytes(&mut bytes_1).unwrap();
219
220        let mut bytes_2 = vec![100];
221        rand_generator.try_fill_bytes(&mut bytes_2).unwrap();
222
223        let mut hash_a = Hasher::new();
224        hash_a.update(&bytes_1);
225        let a = hash_a.finalize();
226
227        let mut hash_b = Hasher::new();
228        hash_b.update(&bytes_2);
229        let b = hash_b.finalize();
230
231        let mut hash_ab = Hasher::new();
232        hash_ab.update(&bytes_1);
233        hash_ab.update(&bytes_2);
234        let ab = hash_ab.finalize();
235
236        let mut reconstructed = Hasher::new_with_initial_len(a, bytes_1.len() as u64);
237        let hash_b_reconstructed = Hasher::new_with_initial_len(b, bytes_2.len() as u64);
238
239        reconstructed.combine(&hash_b_reconstructed);
240
241        assert_eq!(reconstructed.finalize(), ab);
242    }
243}
crc32/lib.rs

crc32/
lib.rs
