]>
Commit | Line | Data |
---|---|---|
3dfed10e XL |
1 | //! Adler-32 checksum implementation. |
2 | //! | |
3 | //! This implementation features: | |
4 | //! | |
5 | //! - Permissively licensed (0BSD) clean-room implementation. | |
6 | //! - Zero dependencies. | |
6a06907d | 7 | //! - Zero `unsafe`. |
3dfed10e XL |
8 | //! - Decent performance (3-4 GB/s). |
9 | //! - `#![no_std]` support (with `default-features = false`). | |
10 | ||
6a06907d | 11 | #![doc(html_root_url = "https://docs.rs/adler/1.0.2")] |
3dfed10e XL |
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"))] | |
20 | extern crate core as std; | |
21 | ||
22 | mod algo; | |
23 | ||
24 | use std::hash::Hasher; | |
25 | ||
26 | #[cfg(feature = "std")] | |
27 | use 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 | |
6a06907d XL |
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 | /// ``` | |
3dfed10e XL |
82 | /// |
83 | /// [`new`]: #method.new | |
84 | /// [`from_checksum`]: #method.from_checksum | |
85 | /// [`checksum`]: #method.checksum | |
86 | #[derive(Debug, Copy, Clone)] | |
87 | pub struct Adler32 { | |
88 | a: u16, | |
89 | b: u16, | |
90 | } | |
91 | ||
92 | impl 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 | ||
147 | impl Default for Adler32 { | |
148 | #[inline] | |
149 | fn default() -> Self { | |
150 | Adler32 { a: 1, b: 0 } | |
151 | } | |
152 | } | |
153 | ||
154 | impl 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. | |
6a06907d XL |
166 | /// |
167 | /// This is a convenience function around the [`Adler32`] type. | |
168 | /// | |
169 | /// [`Adler32`]: struct.Adler32.html | |
3dfed10e XL |
170 | pub fn adler32_slice(data: &[u8]) -> u32 { |
171 | let mut h = Adler32::new(); | |
172 | h.write_slice(data); | |
173 | h.checksum() | |
174 | } | |
175 | ||
176 | /// Calculates the Adler-32 checksum of a `BufRead`'s contents. | |
177 | /// | |
6a06907d XL |
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); | |
3dfed10e | 199 | /// |
6a06907d XL |
200 | /// adler32(&mut file)?; |
201 | /// # Ok(()) } | |
202 | /// # fn main() { run().unwrap() } | |
203 | /// ``` | |
3dfed10e XL |
204 | #[cfg(feature = "std")] |
205 | #[cfg_attr(docsrs, doc(cfg(feature = "std")))] | |
6a06907d | 206 | pub fn adler32<R: BufRead>(mut reader: R) -> io::Result<u32> { |
3dfed10e XL |
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)] | |
223 | mod tests { | |
224 | use super::*; | |
3dfed10e XL |
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 | ||
6a06907d | 271 | #[cfg(feature = "std")] |
3dfed10e XL |
272 | #[test] |
273 | fn bufread() { | |
6a06907d | 274 | use std::io::BufReader; |
3dfed10e XL |
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); | |
6a06907d | 278 | let real_sum = adler32(&mut buf).unwrap(); |
3dfed10e XL |
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 | } |