1//! Adler-32 checksum implementation.
2//!
3//! This implementation features:
4//!
5//! - Permissively licensed (0BSD) clean-room implementation.
6//! - Zero dependencies.
7//! - Zero `unsafe`.
8//! - Decent performance (3-4 GB/s).
9//! - `#![no_std]` support (with `default-features = false`).
10
11#![doc(html_root_url = "https://docs.rs/adler/1.0.2")]
12// Deny a few warnings in doctests, since rustdoc `allow`s many warnings by default
13#![doc(test(attr(deny(unused_imports, unused_must_use))))]
14#![cfg_attr(docsrs, feature(doc_cfg))]
15#![warn(missing_debug_implementations)]
16#![forbid(unsafe_code)]
17#![cfg_attr(not(feature = "std"), no_std)]
18
19#[cfg(not(feature = "std"))]
20extern crate core as std;
21
22mod algo;
23
24use std::hash::Hasher;
25
26#[cfg(feature = "std")]
27use std::io::{self, BufRead};
28
29/// Adler-32 checksum calculator.
30///
31/// An instance of this type is equivalent to an Adler-32 checksum: It can be created in the default
32/// state via [`new`] (or the provided `Default` impl), or from a precalculated checksum via
33/// [`from_checksum`], and the currently stored checksum can be fetched via [`checksum`].
34///
35/// This type also implements `Hasher`, which makes it easy to calculate Adler-32 checksums of any
36/// type that implements or derives `Hash`. This also allows using Adler-32 in a `HashMap`, although
37/// that is not recommended (while every checksum is a hash function, they are not necessarily a
38/// good one).
39///
40/// # Examples
41///
42/// Basic, piecewise checksum calculation:
43///
44/// ```
45/// use adler::Adler32;
46///
47/// let mut adler = Adler32::new();
48///
49/// adler.write_slice(&[0, 1, 2]);
50/// adler.write_slice(&[3, 4, 5]);
51///
52/// assert_eq!(adler.checksum(), 0x00290010);
53/// ```
54///
55/// Using `Hash` to process structures:
56///
57/// ```
58/// use std::hash::Hash;
59/// use adler::Adler32;
60///
61/// #[derive(Hash)]
62/// struct Data {
63/// byte: u8,
64/// word: u16,
65/// big: u64,
66/// }
67///
68/// let mut adler = Adler32::new();
69///
70/// let data = Data { byte: 0x1F, word: 0xABCD, big: !0 };
71/// data.hash(&mut adler);
72///
73/// // hash value depends on architecture endianness
74/// if cfg!(target_endian = "little") {
75/// assert_eq!(adler.checksum(), 0x33410990);
76/// }
77/// if cfg!(target_endian = "big") {
78/// assert_eq!(adler.checksum(), 0x331F0990);
79/// }
80///
81/// ```
82///
83/// [`new`]: #method.new
84/// [`from_checksum`]: #method.from_checksum
85/// [`checksum`]: #method.checksum
86#[derive(Debug, Copy, Clone)]
87pub struct Adler32 {
88 a: u16,
89 b: u16,
90}
91
92impl Adler32 {
93 /// Creates a new Adler-32 instance with default state.
94 #[inline]
95 pub fn new() -> Self {
96 Self::default()
97 }
98
99 /// Creates an `Adler32` instance from a precomputed Adler-32 checksum.
100 ///
101 /// This allows resuming checksum calculation without having to keep the `Adler32` instance
102 /// around.
103 ///
104 /// # Example
105 ///
106 /// ```
107 /// # use adler::Adler32;
108 /// let parts = [
109 /// "rust",
110 /// "acean",
111 /// ];
112 /// let whole = adler::adler32_slice(b"rustacean");
113 ///
114 /// let mut sum = Adler32::new();
115 /// sum.write_slice(parts[0].as_bytes());
116 /// let partial = sum.checksum();
117 ///
118 /// // ...later
119 ///
120 /// let mut sum = Adler32::from_checksum(partial);
121 /// sum.write_slice(parts[1].as_bytes());
122 /// assert_eq!(sum.checksum(), whole);
123 /// ```
124 #[inline]
125 pub fn from_checksum(sum: u32) -> Self {
126 Adler32 {
127 a: sum as u16,
128 b: (sum >> 16) as u16,
129 }
130 }
131
132 /// Returns the calculated checksum at this point in time.
133 #[inline]
134 pub fn checksum(&self) -> u32 {
135 (u32::from(self.b) << 16) | u32::from(self.a)
136 }
137
138 /// Adds `bytes` to the checksum calculation.
139 ///
140 /// If efficiency matters, this should be called with Byte slices that contain at least a few
141 /// thousand Bytes.
142 pub fn write_slice(&mut self, bytes: &[u8]) {
143 self.compute(bytes);
144 }
145}
146
147impl Default for Adler32 {
148 #[inline]
149 fn default() -> Self {
150 Adler32 { a: 1, b: 0 }
151 }
152}
153
154impl Hasher for Adler32 {
155 #[inline]
156 fn finish(&self) -> u64 {
157 u64::from(self.checksum())
158 }
159
160 fn write(&mut self, bytes: &[u8]) {
161 self.write_slice(bytes);
162 }
163}
164
165/// Calculates the Adler-32 checksum of a byte slice.
166///
167/// This is a convenience function around the [`Adler32`] type.
168///
169/// [`Adler32`]: struct.Adler32.html
170pub fn adler32_slice(data: &[u8]) -> u32 {
171 let mut h: Adler32 = Adler32::new();
172 h.write_slice(bytes:data);
173 h.checksum()
174}
175
176/// Calculates the Adler-32 checksum of a `BufRead`'s contents.
177///
178/// The passed `BufRead` implementor will be read until it reaches EOF (or until it reports an
179/// error).
180///
181/// If you only have a `Read` implementor, you can wrap it in `std::io::BufReader` before calling
182/// this function.
183///
184/// # Errors
185///
186/// Any error returned by the reader are bubbled up by this function.
187///
188/// # Examples
189///
190/// ```no_run
191/// # fn run() -> Result<(), Box<dyn std::error::Error>> {
192/// use adler::adler32;
193///
194/// use std::fs::File;
195/// use std::io::BufReader;
196///
197/// let file = File::open("input.txt")?;
198/// let mut file = BufReader::new(file);
199///
200/// adler32(&mut file)?;
201/// # Ok(()) }
202/// # fn main() { run().unwrap() }
203/// ```
204#[cfg(feature = "std")]
205#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
206pub fn adler32<R: BufRead>(mut reader: R) -> io::Result<u32> {
207 let mut h = Adler32::new();
208 loop {
209 let len = {
210 let buf = reader.fill_buf()?;
211 if buf.is_empty() {
212 return Ok(h.checksum());
213 }
214
215 h.write_slice(buf);
216 buf.len()
217 };
218 reader.consume(len);
219 }
220}
221
222#[cfg(test)]
223mod tests {
224 use super::*;
225
226 #[test]
227 fn zeroes() {
228 assert_eq!(adler32_slice(&[]), 1);
229 assert_eq!(adler32_slice(&[0]), 1 | 1 << 16);
230 assert_eq!(adler32_slice(&[0, 0]), 1 | 2 << 16);
231 assert_eq!(adler32_slice(&[0; 100]), 0x00640001);
232 assert_eq!(adler32_slice(&[0; 1024]), 0x04000001);
233 assert_eq!(adler32_slice(&[0; 1024 * 1024]), 0x00f00001);
234 }
235
236 #[test]
237 fn ones() {
238 assert_eq!(adler32_slice(&[0xff; 1024]), 0x79a6fc2e);
239 assert_eq!(adler32_slice(&[0xff; 1024 * 1024]), 0x8e88ef11);
240 }
241
242 #[test]
243 fn mixed() {
244 assert_eq!(adler32_slice(&[1]), 2 | 2 << 16);
245 assert_eq!(adler32_slice(&[40]), 41 | 41 << 16);
246
247 assert_eq!(adler32_slice(&[0xA5; 1024 * 1024]), 0xd5009ab1);
248 }
249
250 /// Example calculation from https://en.wikipedia.org/wiki/Adler-32.
251 #[test]
252 fn wiki() {
253 assert_eq!(adler32_slice(b"Wikipedia"), 0x11E60398);
254 }
255
256 #[test]
257 fn resume() {
258 let mut adler = Adler32::new();
259 adler.write_slice(&[0xff; 1024]);
260 let partial = adler.checksum();
261 assert_eq!(partial, 0x79a6fc2e); // from above
262 adler.write_slice(&[0xff; 1024 * 1024 - 1024]);
263 assert_eq!(adler.checksum(), 0x8e88ef11); // from above
264
265 // Make sure that we can resume computing from the partial checksum via `from_checksum`.
266 let mut adler = Adler32::from_checksum(partial);
267 adler.write_slice(&[0xff; 1024 * 1024 - 1024]);
268 assert_eq!(adler.checksum(), 0x8e88ef11); // from above
269 }
270
271 #[cfg(feature = "std")]
272 #[test]
273 fn bufread() {
274 use std::io::BufReader;
275 fn test(data: &[u8], checksum: u32) {
276 // `BufReader` uses an 8 KB buffer, so this will test buffer refilling.
277 let mut buf = BufReader::new(data);
278 let real_sum = adler32(&mut buf).unwrap();
279 assert_eq!(checksum, real_sum);
280 }
281
282 test(&[], 1);
283 test(&[0; 1024], 0x04000001);
284 test(&[0; 1024 * 1024], 0x00f00001);
285 test(&[0xA5; 1024 * 1024], 0xd5009ab1);
286 }
287}
288