crc32/

lib.rs

//! Fast, SIMD-accelerated CRC32 (IEEE) checksum computation.
//!
//! ## Usage
//!
//! ### Simple usage
//!
//! For simple use-cases, you can call the [`hash()`] convenience function to
//! directly compute the CRC32 checksum for a given byte slice:
//!
//! ```rust
//! let checksum = crc32::hash(b"foo bar baz");
//! ```
//!
//! ### Advanced usage
//!
//! For use-cases that require more flexibility or performance, for example when
//! processing large amounts of data, you can create and manipulate a [`Hasher`]:
//!
//! ```rust
//! use crc32::Hasher;
//!
//! let mut hasher = Hasher::new();
//! hasher.update(b"foo bar baz");
//! let checksum = hasher.finalize();
//! ```
//!
//! ## Performance
//!
//! This crate contains multiple CRC32 implementations:
//!
//! - A fast baseline implementation which processes up to 16 bytes per iteration
//! - An optimized implementation for modern `x86` using `sse` and `pclmulqdq` instructions
//! - An optimized implementation for `aarch64` using the `crc32` instructions
//!
//! Calling the [`Hasher::new`] constructor at runtime will perform a feature
//! detection to select the most optimal implementation for the current CPU
//! feature set.
//!
//! ## Memory safety
//!
//! Due to the use of SIMD intrinsics for the optimized implementations, this
//! crate contains some amount of `unsafe` code. The baseline implementation is
//! safe, and the specialized implementations are exercised by the crate's
//! tests, which are only compiled when the `std` feature is enabled.
//!
//! ## Feature flags
//!
//! ### `std` (default: enabled)
//!
//! The crate can be built without the Rust `std` library, which is useful for
//! low-level use-cases such as embedded where no operating system is available.
//! To build the crate in a `no_std` context, disable the default `std` feature.
//!
//! Because runtime CPU feature detection requires OS support, the specialized
//! SIMD implementations are unavailable when the `std` feature is disabled.
//!
//! ### `nightly` (default: disabled)
//!
//! Enables unstable features that are only available on the `nightly` channel.
//! Enabling it makes the optimized `aarch64` implementation available.

#![cfg_attr(not(feature = "std"), no_std)]

// #[deny(missing_docs)]
// #[cfg(test)]
// #[macro_use]
// extern crate quickcheck;

use core::{fmt, hash};
#[cfg(feature = "std")]
use std as core;

mod baseline;
mod combine;
mod specialized;
mod table;

/// Computes the CRC32 hash of a byte slice.
///
/// Check out [`Hasher`] for more advanced use-cases.
pub fn hash(buf: &[u8]) -> u32 {
    let mut h = Hasher::new();
    h.update(buf);
    h.finalize()
}

#[derive(Clone)]
enum State {
    Baseline(baseline::State),
    Specialized(specialized::State),
}

#[derive(Clone)]
/// Represents an in-progress CRC32 computation.
pub struct Hasher {
    amount: u64,
    state: State,
}

const DEFAULT_INIT_STATE: u32 = 0;

impl Hasher {
    /// Create a new `Hasher`.
    ///
    /// This will perform a CPU feature detection at runtime to select the most
    /// optimal implementation for the current processor architecture.
    pub fn new() -> Self {
        Self::new_with_initial(DEFAULT_INIT_STATE)
    }

    /// Create a new `Hasher` with an initial CRC32 state.
    ///
    /// This works just like `Hasher::new`, except that it allows for an initial
    /// CRC32 state to be passed in.
    pub fn new_with_initial(init: u32) -> Self {
        Self::new_with_initial_len(init, 0)
    }

    /// Create a new `Hasher` with an initial CRC32 state.
    ///
    /// As `new_with_initial`, but also accepts a length (in bytes). The
    /// resulting object can then be used with `combine` to compute `crc(a ||
    /// b)` from `crc(a)`, `crc(b)`, and `len(b)`.
    pub fn new_with_initial_len(init: u32, amount: u64) -> Self {
        Self::internal_new_specialized(init, amount).unwrap_or_else(|| Self::internal_new_baseline(init, amount))
    }

    #[doc(hidden)]
    // Internal-only API. Don't use.
    pub fn internal_new_baseline(init: u32, amount: u64) -> Self {
        Hasher {
            amount,
            state: State::Baseline(baseline::State::new(init)),
        }
    }

    #[doc(hidden)]
    // Internal-only API. Don't use.
    pub fn internal_new_specialized(init: u32, amount: u64) -> Option<Self> {
        {
            if let Some(state) = specialized::State::new(init) {
                return Some(Hasher {
                    amount,
                    state: State::Specialized(state),
                });
            }
        }
        None
    }

    /// Process the given byte slice and update the hash state.
    pub fn update(&mut self, buf: &[u8]) {
        self.amount += buf.len() as u64;
        match self.state {
            State::Baseline(ref mut state) => state.update(buf),
            State::Specialized(ref mut state) => state.update(buf),
        }
    }

    /// Finalize the hash state and return the computed CRC32 value.
    pub fn finalize(self) -> u32 {
        match self.state {
            State::Baseline(state) => state.finalize(),
            State::Specialized(state) => state.finalize(),
        }
    }

    /// Reset the hash state.
    pub fn reset(&mut self) {
        self.amount = 0;
        match self.state {
            State::Baseline(ref mut state) => state.reset(),
            State::Specialized(ref mut state) => state.reset(),
        }
    }

    /// Combine the hash state with the hash state for the subsequent block of bytes.
    pub fn combine(&mut self, other: &Self) {
        self.amount += other.amount;
        let other_crc = other.clone().finalize();
        match self.state {
            State::Baseline(ref mut state) => state.combine(other_crc, other.amount),
            State::Specialized(ref mut state) => state.combine(other_crc, other.amount),
        }
    }
}

impl fmt::Debug for Hasher {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.debug_struct("crc32::Hasher").finish()
    }
}

impl Default for Hasher {
    fn default() -> Self {
        Self::new()
    }
}

impl hash::Hasher for Hasher {
    fn write(&mut self, bytes: &[u8]) {
        self.update(bytes)
    }

    fn finish(&self) -> u64 {
        u64::from(self.clone().finalize())
    }
}

#[cfg(all(test, feature = "std"))]
mod test {
    use rand::{TryRng, rngs::SysRng};

    use super::Hasher;

    #[test]
    fn combine() {
        let mut rand_generator = SysRng;

        let mut bytes_1 = vec![100];
        rand_generator.try_fill_bytes(&mut bytes_1).unwrap();

        let mut bytes_2 = vec![200];
        rand_generator.try_fill_bytes(&mut bytes_2).unwrap();

        let mut hash_a = Hasher::new();
        hash_a.update(&bytes_1);
        hash_a.update(&bytes_2);
        let mut hash_b = Hasher::new();
        hash_b.update(&bytes_2);
        let mut hash_c = Hasher::new();
        hash_c.update(&bytes_1);
        hash_c.combine(&hash_b);

        assert_eq!(hash_a.finalize(), hash_c.finalize());
    }

    #[test]
    fn combine_from_len() {
        let mut rand_generator = SysRng;

        let mut bytes_1 = vec![200];
        rand_generator.try_fill_bytes(&mut bytes_1).unwrap();

        let mut bytes_2 = vec![100];
        rand_generator.try_fill_bytes(&mut bytes_2).unwrap();

        let mut hash_a = Hasher::new();
        hash_a.update(&bytes_1);
        let a = hash_a.finalize();

        let mut hash_b = Hasher::new();
        hash_b.update(&bytes_2);
        let b = hash_b.finalize();

        let mut hash_ab = Hasher::new();
        hash_ab.update(&bytes_1);
        hash_ab.update(&bytes_2);
        let ab = hash_ab.finalize();

        let mut reconstructed = Hasher::new_with_initial_len(a, bytes_1.len() as u64);
        let hash_b_reconstructed = Hasher::new_with_initial_len(b, bytes_2.len() as u64);

        reconstructed.combine(&hash_b_reconstructed);

        assert_eq!(reconstructed.finalize(), ab);
    }
}