fnv64-rs 0.2.2 

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
98
99

//! 🦀 FNV-1a Hashing Implementation
//!
//! This module provides the **FNV-1a** 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::fvn1a::*`.
//!
//! ### đź’ˇ Algorithm Logic
//! FNV-1a is the most widely recommended variant of FNV. It differs from FNV-1 by using an
//! **XOR-then-Multiply** sequence, which significantly improves the "avalanche characteristics"
//! (how much the hash changes when a single bit of input changes).
//!
//! 1. Start with the [`OFFSET_BASIS`][`crate::OFFSET`].
//! 2. For each byte:
//!    * XOR the current hash with the byte.
//!    * Multiply the result by the [`FNV_PRIME`][`crate::PRIME`].
//!
//! ### 🛠️ Usage
//! This module provides the [`Fvn1aHasher`] and the [`Fvn1aBuildHasher`].
//! FNV-1a is the default choice for [`FvnHashMap`](crate::FvnHashMap).
//!
//! ```rust
//! use core::hash::Hasher;
//! use fnv64_rs::Fvn1aHasher;
//!
//! let mut hasher = Fvn1aHasher::default();
//! hasher.write(b"Rust");
//! let result = hasher.finish();
//! ```
use core::hash::{BuildHasher, Hasher};

/// A generic implementation of the FNV-1a (Fowler–Noll–Vo) hashing algorithm.
///
/// FNV-1a is a variation of the FNV-1 algorithm that changes the order of the
/// XOR and multiplication steps. This usually results in better "avalanche"
/// characteristics for short strings.
pub struct GenericFvn1aHasher<const OFFSET: u64, const PRIME: u64> {
    hash: u64,
}

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

    /// Performs the FNV-1a hash transformation: `hash = (hash ^ byte) * PRIME`.
    ///
    /// This implementation uses wrapping multiplication to ensure consistent
    /// behavior across debug and release profiles, as the algorithm relies
    /// on 64-bit integer overflow.
    #[inline]
    fn write(&mut self, bytes: &[u8]) {
        for byte in bytes {
            // FNV-1a: XOR then Multiply
            self.hash ^= *byte as u64;
            self.hash = self.hash.wrapping_mul(PRIME);
        }
    }
}

impl<const OFFSET: u64, const PRIME: u64> Default for GenericFvn1aHasher<OFFSET, PRIME> {
    /// Initializes the hasher with the provided `OFFSET` basis.
    fn default() -> Self {
        Self { hash: OFFSET }
    }
}

/// A builder for creating [`GenericFvn1aHasher`] instances with specific parameters.
///
/// This is useful for integrating with collections like `HashMap` or `HashSet`
/// that require a `BuildHasher` to initialize their internal hashing state.
pub struct GenericFvn1aBuildHasher<const OFFSET: u64, const PRIME: u64> {}

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

    #[inline]
    fn build_hasher(&self) -> Self::Hasher {
        GenericFvn1aHasher::default()
    }
}

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

/// Standard 64-bit FNV-1a hasher using the official FNV offset basis and prime.
///
/// This is the most common 64-bit FNV variant used in modern applications.
pub type Fvn1aHasher = GenericFvn1aHasher<{ crate::OFFSET }, { crate::PRIME }>;

/// Standard 64-bit FNV-1a build hasher.
///
/// Use this to initialize a `HashMap` with FNV-1a:
/// `let mut map: HashMap<K, V, Fvn1aBuildHasher> = HashMap::default();`
pub type Fvn1aBuildHasher = GenericFvn1aBuildHasher<{ crate::OFFSET }, { crate::PRIME }>;