JenkHash 0.2.0

//! Hash trait definitions for JenkHash.
//!
//! This module provides the [`Hasher`] trait, which defines a unified interface
//! for all hash functions in this crate. This trait allows different hash algorithms
//! to be used interchangeably while providing a simple, efficient API.

/// A trait for hashing algorithms.
///
/// This trait provides a unified interface for incremental hashing. Implementations
/// can process input data in chunks and produce a final hash value. The trait is
/// designed to be simple and efficient, avoiding the complexity of other hash trait
/// systems.
///
/// # Type Parameters
///
/// * `Output` - The type of the hash value produced by this hasher (typically `u32` or `u64`)
///
/// # Examples
///
/// ```
/// use JenkHash::{Hasher, OneAtATime};
///
/// let mut hasher = OneAtATime::new();
/// hasher.write(b"hello");
/// hasher.write(b" world");
/// let hash = hasher.finalize();
/// ```
pub trait Hasher {
    /// The type of hash value produced by this hasher.
    type Output;

    /// Creates a new hasher instance with a default initial state.
    ///
    /// # Examples
    ///
    /// ```
    /// use JenkHash::{Hasher, OneAtATime};
    ///
    /// let hasher = OneAtATime::new();
    /// ```
    fn new() -> Self;

    /// Writes data into the hasher.
    ///
    /// This method can be called multiple times to incrementally add data to the hash.
    /// The data will be processed and incorporated into the hash state.
    ///
    /// # Arguments
    ///
    /// * `input` - The byte slice to add to the hash
    ///
    /// # Examples
    ///
    /// ```
    /// use JenkHash::{Hasher, OneAtATime};
    ///
    /// let mut hasher = OneAtATime::new();
    /// hasher.write(b"hello");
    /// hasher.write(b" world");
    /// ```
    fn write(&mut self, input: &[u8]) {}

    /// Writes an array of 32-bit words into the hasher.
    ///
    /// This is an optional method for hashers that can efficiently process word-aligned
    /// data. The default implementation does nothing, and hashers that don't support
    /// this operation can ignore it.
    ///
    /// # Arguments
    ///
    /// * `input` - The slice of 32-bit words to add to the hash
    fn write_u32(&mut self, input: &[u64]) {}

    /// Writes an array of 64-bit words into the hasher.
    ///
    /// This is an optional method for hashers that can efficiently process word-aligned
    /// data. The default implementation does nothing, and hashers that don't support
    /// this operation can ignore it.
    ///
    /// # Arguments
    ///
    /// * `input` - The slice of 64-bit words to add to the hash
    fn write_u64(&mut self, input: &[u64]) {}

    /// Finalizes the hash and returns the result.
    ///
    /// This method consumes the hasher and returns the final hash value. After calling
    /// this method, the hasher cannot be used again.
    ///
    /// # Returns
    ///
    /// The final hash value of type `Self::Output`.
    ///
    /// # Examples
    ///
    /// ```
    /// use JenkHash::{Hasher, OneAtATime};
    ///
    /// let mut hasher = OneAtATime::new();
    /// hasher.write(b"hello world");
    /// let hash = hasher.finalize();
    /// ```
    #[must_use]
    fn finalize(self) -> Self::Output;
}