fnv64-rs 0.3.5

A lightweight, zero-dependency implementation of the FNV (Fowler–Noll–Vo) hash function.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

//! 🦀 FNV-1 Hashing Implementation
//!
//! This module provides the **FNV-1** variant of the Fowler–Noll–Vo hash function.
//!
//! **Note: All types in this module are re-exported at the crate root.** You can use them
//! via `fnv64_rs::*` instead of `fnv64_rs::fnv1::*`.
//!
//! ### 💡 Algorithm Logic
//! The FNV-1 algorithm follows a **Multiply-then-XOR** sequence:
//! 1. Start with the [`OFFSET_BASIS`][`crate::OFFSET`].
//! 2. For each byte:
//!    * Multiply the current hash by the [`FNV_PRIME`][`crate::PRIME`].
//!    * XOR the result with the byte.
//!
//! ### 🛠️ Usage
//! This module provides both the raw [`Fnv1Hasher`] and the [`Fnv1BuildHasher`] for use with collections.
//!
//! ```rust
//! use core::hash::Hasher;
//! use fnv64_rs::Fnv1Hasher;
//!
//! let mut hasher = Fnv1Hasher::default();
//! hasher.write(b"Rust");
//! let result = hasher.finish();
//! ```

use core::clone::Clone;
use core::fmt::Debug;
use core::hash::{BuildHasher, Hasher};

/// A generic implementation of the FNV-1 (Fowler–Noll–Vo) hashing algorithm.
///
/// This struct uses const generics for the `OFFSET` and `PRIME` to allow
/// support for different bit-widths or custom variants while maintaining
/// zero-cost abstractions.
#[derive(Clone, Debug)]
pub struct GenericFnv1Hasher<const OFFSET: u64, const PRIME: u64> {
    hash: u64,
}

impl<const OFFSET: u64, const PRIME: u64> Hasher for GenericFnv1Hasher<OFFSET, PRIME> {
    #[inline]
    fn finish(&self) -> u64 {
        self.hash
    }

    /// Performs the FNV-1 hash transformation: `hash = (hash * PRIME) ^ byte`.
    ///
    /// Note: This uses wrapping multiplication to prevent panics in debug builds,
    /// as the FNV algorithm relies on integer overflow behavior.
    fn write(&mut self, bytes: &[u8]) {
        for byte in bytes {
            // FNV-1: Multiply then XOR
            self.hash = self.hash.wrapping_mul(PRIME);
            self.hash ^= *byte as u64;
        }
    }
}

impl<const OFFSET: u64, const PRIME: u64> Default for GenericFnv1Hasher<OFFSET, PRIME> {
    fn default() -> Self {
        Self { hash: OFFSET }
    }
}

/// A builder for creating [`GenericFnv1Hasher`] instances with specific parameters.
#[derive(Clone, Debug)]
pub struct GenericFnv1BuildHasher<const OFFSET: u64, const PRIME: u64> {}

impl<const OFFSET: u64, const PRIME: u64> BuildHasher for GenericFnv1BuildHasher<OFFSET, PRIME> {
    type Hasher = GenericFnv1Hasher<OFFSET, PRIME>;

    fn build_hasher(&self) -> Self::Hasher {
        GenericFnv1Hasher::default()
    }
}

impl<const OFFSET: u64, const PRIME: u64> Default for GenericFnv1BuildHasher<OFFSET, PRIME> {
    fn default() -> Self {
        Self {}
    }
}

/// Standard 64-bit FNV-1 hasher using the official FNV offset basis and prime.
pub type Fnv1Hasher = GenericFnv1Hasher<{ crate::OFFSET }, { crate::PRIME }>;

/// Standard 64-bit FNV-1 build hasher.
pub type Fnv1BuildHasher = GenericFnv1BuildHasher<{ crate::OFFSET }, { crate::PRIME }>;

/// FNV-0 variant hasher (deprecated in general use).
///
/// FNV-0 uses an initial state of `0` instead of a specific offset basis.
/// It is generally only used for historical purposes or specific hashing benchmarks.
pub type Fnv0Hasher = GenericFnv1Hasher<0, { crate::PRIME }>;

/// FNV-0 build hasher.
pub type Fnv0BuildHasher = GenericFnv1BuildHasher<0, { crate::PRIME }>;