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