vendor/adler/src/lib.rs

   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"))]
  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
  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)]
  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.
 166 ///
 167 /// This is a convenience function around the [`Adler32`] type.
 168 ///
 169 /// [`Adler32`]: struct.Adler32.html
 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 ///
 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")))]
 206 pub 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)]
 223 mod 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 }