Refactor: split lib.rs into separate module files

Split the monolithic 2206-line lib.rs into focused module files:
- hex.rs: hex character parsing utilities
- classic.rs: classic popcount and hamming distance implementations
- native.rs: native CPU popcount implementations
- x86_simd.rs: x86_64 SSE4.1/AVX2/AVX-512 SIMD implementations
- neon_simd.rs: ARM64 NEON SIMD implementations
- python.rs: Python/PyO3 bindings
- api.rs: public Rust API functions
- tests.rs: unit tests

lib.rs retains constants, global state, module declarations,
dispatch functions, and re-exports the public API.

No logic changes — only code movement and visibility adjustments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mrecachinas

src/api.rs

@@ -0,0 +1,230 @@
+use crate::{
+    hamming_distance_bytes_dispatch, hamming_distance_string_dispatch,
+    ALGO_CLASSIC, ALGO_NATIVE,
+    CURRENT_ALGO,
+};
+#[cfg(target_arch = "x86_64")]
+use crate::{ALGO_AVX2, ALGO_AVX512, ALGO_SSE41};
+
+use std::sync::atomic::Ordering;
+
+/// Calculate the bitwise hamming distance between two equal-length hex strings.
+///
+/// Automatically uses the best SIMD implementation available (NEON/AVX2/SSE4.1).
+///
+/// # Errors
+/// Returns `Err` if the strings differ in length or contain non-hex characters.
+///
+/// # Example
+/// ```
+/// let dist = hexhamming::hex_hamming_distance("deadbeef", "00000000").unwrap();
+/// assert_eq!(dist, 24);
+/// ```
+pub fn hex_hamming_distance(a: &str, b: &str) -> Result<u64, &'static str> {
+    if a.len() != b.len() {
+        return Err("strings are NOT the same length");
+    }
+    if a.is_empty() {
+        return Ok(0);
+    }
+    hamming_distance_string_dispatch(a.as_bytes(), b.as_bytes())
+}
+
+/// Calculate the bitwise hamming distance between two equal-length byte slices.
+///
+/// Automatically uses the best SIMD implementation available (NEON/AVX2/SSE4.1).
+///
+/// # Errors
+/// Returns `Err` if the slices differ in length.
+///
+/// # Example
+/// ```
+/// let dist = hexhamming::bytes_hamming_distance(b"\xff", b"\x00").unwrap();
+/// assert_eq!(dist, 8);
+/// ```
+pub fn bytes_hamming_distance(a: &[u8], b: &[u8]) -> Result<u64, &'static str> {
+    if a.len() != b.len() {
+        return Err("bytes are NOT the same length");
+    }
+    if a.is_empty() {
+        return Ok(0);
+    }
+    Ok(hamming_distance_bytes_dispatch(a, b, -1))
+}
+
+/// Check if two byte arrays are within a specified Hamming distance.
+///
+/// Returns `Ok(true)` if distance <= max_dist, `Ok(false)` otherwise.
+pub fn bytes_within_dist(a: &[u8], b: &[u8], max_dist: i64) -> Result<bool, &'static str> {
+    if a.is_empty() || b.is_empty() {
+        return Err("array size must be >0");
+    }
+    if a.len() != b.len() {
+        return Err("array sizes need to be the same");
+    }
+    Ok(hamming_distance_bytes_dispatch(a, b, max_dist) == 1)
+}
+
+/// Find the first element in a byte array within a specified Hamming distance.
+///
+/// Returns the index of the first matching element, or `None`.
+pub fn bytes_array_first_within_dist(big_array: &[u8], small_array: &[u8], max_dist: i64) -> Result<Option<usize>, &'static str> {
+    if small_array.is_empty() {
+        return Err("elem_to_compare size must be >0");
+    }
+    if big_array.len() % small_array.len() != 0 {
+        return Err("array_of_elems size must be multiplier of elem_to_compare");
+    }
+    let elem_size = small_array.len();
+    let num_elements = big_array.len() / elem_size;
+    for i in 0..num_elements {
+        let chunk = &big_array[i * elem_size..(i + 1) * elem_size];
+        if hamming_distance_bytes_dispatch(chunk, small_array, max_dist) == 1 {
+            return Ok(Some(i));
+        }
+    }
+    Ok(None)
+}
+
+/// Find the element in a byte array with the smallest Hamming distance.
+///
+/// Returns `Some((distance, index))` of the best match, or `None` if none within max_dist.
+pub fn bytes_array_best_within_dist(big_array: &[u8], small_array: &[u8], max_dist: i64) -> Result<Option<(u64, usize)>, &'static str> {
+    if small_array.is_empty() {
+        return Err("elem_to_compare size must be >0");
+    }
+    if big_array.len() % small_array.len() != 0 {
+        return Err("array_of_elems size must be multiplier of elem_to_compare");
+    }
+    let elem_size = small_array.len();
+    let num_elements = big_array.len() / elem_size;
+    let mut best_dist: i64 = -1;
+    let mut best_index: Option<usize> = None;
+
+    for i in 0..num_elements {
+        let chunk = &big_array[i * elem_size..(i + 1) * elem_size];
+        let threshold = if best_dist >= 0 { best_dist - 1 } else { max_dist };
+        if hamming_distance_bytes_dispatch(chunk, small_array, threshold) == 0 {
+            continue;
+        }
+        let dist = hamming_distance_bytes_dispatch(chunk, small_array, -1) as i64;
+        if best_dist < 0 || dist < best_dist {
+            best_dist = dist;
+            best_index = Some(i);
+        }
+    }
+    Ok(best_index.map(|idx| (best_dist as u64, idx)))
+}
+
+/// Find all elements in a byte array within a specified Hamming distance.
+///
+/// Returns a Vec of `(distance, index)` tuples.
+pub fn bytes_array_all_within_dist(big_array: &[u8], small_array: &[u8], max_dist: i64) -> Result<Vec<(u64, usize)>, &'static str> {
+    if small_array.is_empty() {
+        return Err("elem_to_compare size must be >0");
+    }
+    if big_array.len() % small_array.len() != 0 {
+        return Err("array_of_elems size must be multiplier of elem_to_compare");
+    }
+    let elem_size = small_array.len();
+    let num_elements = big_array.len() / elem_size;
+    let mut results = Vec::new();
+
+    for i in 0..num_elements {
+        let chunk = &big_array[i * elem_size..(i + 1) * elem_size];
+        if hamming_distance_bytes_dispatch(chunk, small_array, max_dist) == 0 {
+            continue;
+        }
+        let dist = hamming_distance_bytes_dispatch(chunk, small_array, -1);
+        results.push((dist, i));
+    }
+    Ok(results)
+}
+
+/// Experimental: hex hamming distance using pack-to-bytes approach.
+/// Parses 32 hex chars → 16 packed bytes, then uses vcntq_u8.
+#[cfg(target_arch = "aarch64")]
+pub fn hex_hamming_distance_pack(a: &str, b: &str) -> Result<u64, &'static str> {
+    if a.len() != b.len() {
+        return Err("strings are NOT the same length");
+    }
+    if a.is_empty() {
+        return Ok(0);
+    }
+    unsafe { crate::neon_simd::hamming_distance_string_neon_pack(a.as_bytes(), b.as_bytes()) }
+}
+
+/// Set the SIMD algorithm used for hamming distance calculations.
+///
+/// Valid algorithm names:
+/// - `"avx512"` / `"avx-512"` — AVX-512 BITALG (requires avx512bw + avx512bitalg)
+/// - `"avx2"` / `"avx"` / `"extra"` — AVX2
+/// - `"sse41"` / `"sse"` — SSE4.1
+/// - `"neon"` — ARM NEON (aarch64 only)
+/// - `"native"` / `"popcount"` — platform native
+/// - `"classic"` — scalar fallback
+///
+/// Returns `Ok(())` on success, `Err` if the CPU doesn't support the requested algorithm.
+pub fn set_algorithm(algo_name: &str) -> Result<(), &'static str> {
+    match algo_name.to_lowercase().as_str() {
+        "avx512" | "avx-512" => {
+            #[cfg(target_arch = "x86_64")]
+            {
+                if is_x86_feature_detected!("avx512bw") && is_x86_feature_detected!("avx512bitalg") {
+                    CURRENT_ALGO.store(ALGO_AVX512, Ordering::Relaxed);
+                    return Ok(());
+                }
+                return Err("CPU doesn't support AVX-512 BITALG");
+            }
+            #[cfg(not(target_arch = "x86_64"))]
+            Err("AVX-512 not available on this architecture")
+        }
+        "extra" | "avx" | "avx2" => {
+            #[cfg(target_arch = "x86_64")]
+            {
+                if is_x86_feature_detected!("avx2") {
+                    CURRENT_ALGO.store(ALGO_AVX2, Ordering::Relaxed);
+                    return Ok(());
+                }
+                return Err("CPU doesn't support AVX2");
+            }
+            #[cfg(target_arch = "aarch64")]
+            {
+                CURRENT_ALGO.store(crate::ALGO_NEON, Ordering::Relaxed);
+                Ok(())
+            }
+            #[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
+            Err("not available on this architecture")
+        }
+        "sse41" | "sse" => {
+            #[cfg(target_arch = "x86_64")]
+            {
+                if is_x86_feature_detected!("sse4.1") {
+                    CURRENT_ALGO.store(ALGO_SSE41, Ordering::Relaxed);
+                    return Ok(());
+                }
+                Err("CPU doesn't support SSE4.1")
+            }
+            #[cfg(not(target_arch = "x86_64"))]
+            Err("SSE not available on this architecture")
+        }
+        "neon" => {
+            #[cfg(target_arch = "aarch64")]
+            {
+                CURRENT_ALGO.store(crate::ALGO_NEON, Ordering::Relaxed);
+                Ok(())
+            }
+            #[cfg(not(target_arch = "aarch64"))]
+            Err("NEON not available on this architecture")
+        }
+        "native" | "popcount" => {
+            CURRENT_ALGO.store(ALGO_NATIVE, Ordering::Relaxed);
+            Ok(())
+        }
+        "classic" => {
+            CURRENT_ALGO.store(ALGO_CLASSIC, Ordering::Relaxed);
+            Ok(())
+        }
+        _ => Err("unknown algorithm"),
+    }
+}

src/classic.rs

@@ -0,0 +1,148 @@
+use crate::hex::hex_char_to_nibble;
+use crate::LOOKUP;
+
+/// Classic popcount implementation using bit manipulation (Wilkes-Wheeler-Gill)
+#[inline(always)]
+pub(crate) fn popcnt64_classic(mut x: u64) -> u64 {
+    const M1: u64 = 0x5555555555555555;
+    const M2: u64 = 0x3333333333333333;
+    const M4: u64 = 0x0F0F0F0F0F0F0F0F;
+    const H01: u64 = 0x0101010101010101;
+    x -= (x >> 1) & M1;
+    x = (x & M2) + ((x >> 2) & M2);
+    x = (x + (x >> 4)) & M4;
+    (x.wrapping_mul(H01)) >> 56
+}
+
+/// Calculate hamming distance between two hex strings using classic algorithm
+/// Optimized with branchless lookup and bounds check elimination
+#[inline(always)]
+pub(crate) fn hamming_distance_string_classic(a: &[u8], b: &[u8]) -> Result<u64, &'static str> {
+    let len = a.len();
+    let mut result: u64 = 0;
+    let mut i = 0;
+    
+    // Process 4 hex chars at a time to reduce loop overhead
+    while i + 4 <= len {
+        // SAFETY: i + 3 < len verified by loop condition
+        unsafe {
+            let val1_0 = hex_char_to_nibble(*a.get_unchecked(i));
+            let val2_0 = hex_char_to_nibble(*b.get_unchecked(i));
+            let val1_1 = hex_char_to_nibble(*a.get_unchecked(i + 1));
+            let val2_1 = hex_char_to_nibble(*b.get_unchecked(i + 1));
+            let val1_2 = hex_char_to_nibble(*a.get_unchecked(i + 2));
+            let val2_2 = hex_char_to_nibble(*b.get_unchecked(i + 2));
+            let val1_3 = hex_char_to_nibble(*a.get_unchecked(i + 3));
+            let val2_3 = hex_char_to_nibble(*b.get_unchecked(i + 3));
+            
+            // Check all 8 values for validity (0xFF indicates invalid)
+            // Use bitwise OR to combine checks - any 0xFF will result in high bit set
+            let invalid = (val1_0 | val2_0 | val1_1 | val2_1 | val1_2 | val2_2 | val1_3 | val2_3) & 0xF0;
+            if invalid != 0 {
+                return Err("hex string contains invalid char");
+            }
+            
+            result += *LOOKUP.get_unchecked((val1_0 ^ val2_0) as usize) as u64
+                   + *LOOKUP.get_unchecked((val1_1 ^ val2_1) as usize) as u64
+                   + *LOOKUP.get_unchecked((val1_2 ^ val2_2) as usize) as u64
+                   + *LOOKUP.get_unchecked((val1_3 ^ val2_3) as usize) as u64;
+        }
+        i += 4;
+    }
+    
+    // Handle remaining characters
+    while i < len {
+        // SAFETY: i < len verified by loop condition
+        unsafe {
+            let val1 = hex_char_to_nibble(*a.get_unchecked(i));
+            let val2 = hex_char_to_nibble(*b.get_unchecked(i));
+            if (val1 | val2) & 0xF0 != 0 {
+                return Err("hex string contains invalid char");
+            }
+            result += *LOOKUP.get_unchecked((val1 ^ val2) as usize) as u64;
+        }
+        i += 1;
+    }
+    
+    Ok(result)
+}
+
+/// Calculate hamming distance between two byte arrays using classic algorithm
+/// Optimized with loop unrolling and bounds check elimination
+#[inline(always)]
+pub(crate) fn hamming_distance_bytes_classic(a: &[u8], b: &[u8], max_dist: i64) -> u64 {
+    let length = a.len();
+
+    if max_dist < 0 {
+        // Full distance calculation - heavily optimized
+        let mut difference: u64 = 0;
+        let mut i = 0;
+        
+        // Process 32 bytes at a time (4 x 8-byte chunks)
+        while i + 32 <= length {
+            // SAFETY: i + 31 < length verified by loop condition
+            unsafe {
+                let a0 = u64::from_ne_bytes(*(a.as_ptr().add(i) as *const [u8; 8]));
+                let b0 = u64::from_ne_bytes(*(b.as_ptr().add(i) as *const [u8; 8]));
+                let a1 = u64::from_ne_bytes(*(a.as_ptr().add(i + 8) as *const [u8; 8]));
+                let b1 = u64::from_ne_bytes(*(b.as_ptr().add(i + 8) as *const [u8; 8]));
+                let a2 = u64::from_ne_bytes(*(a.as_ptr().add(i + 16) as *const [u8; 8]));
+                let b2 = u64::from_ne_bytes(*(b.as_ptr().add(i + 16) as *const [u8; 8]));
+                let a3 = u64::from_ne_bytes(*(a.as_ptr().add(i + 24) as *const [u8; 8]));
+                let b3 = u64::from_ne_bytes(*(b.as_ptr().add(i + 24) as *const [u8; 8]));
+                
+                difference += popcnt64_classic(a0 ^ b0)
+                           + popcnt64_classic(a1 ^ b1)
+                           + popcnt64_classic(a2 ^ b2)
+                           + popcnt64_classic(a3 ^ b3);
+            }
+            i += 32;
+        }
+        
+        // Process remaining 8-byte chunks
+        while i + 8 <= length {
+            unsafe {
+                let a_chunk = u64::from_ne_bytes(*(a.as_ptr().add(i) as *const [u8; 8]));
+                let b_chunk = u64::from_ne_bytes(*(b.as_ptr().add(i) as *const [u8; 8]));
+                difference += popcnt64_classic(a_chunk ^ b_chunk);
+            }
+            i += 8;
+        }
+        
+        // Process remaining bytes
+        while i < length {
+            unsafe {
+                difference += popcnt64_classic((*a.get_unchecked(i) ^ *b.get_unchecked(i)) as u64);
+            }
+            i += 1;
+        }
+        difference
+    } else {
+        // Early termination if exceeds max_dist
+        let max_dist_u64 = max_dist as u64;
+        let mut difference: u64 = 0;
+        let mut i = 0;
+        
+        while i + 8 <= length {
+            unsafe {
+                let a_chunk = u64::from_ne_bytes(*(a.as_ptr().add(i) as *const [u8; 8]));
+                let b_chunk = u64::from_ne_bytes(*(b.as_ptr().add(i) as *const [u8; 8]));
+                difference += popcnt64_classic(a_chunk ^ b_chunk);
+            }
+            if difference > max_dist_u64 {
+                return 0;
+            }
+            i += 8;
+        }
+        while i < length {
+            unsafe {
+                difference += popcnt64_classic((*a.get_unchecked(i) ^ *b.get_unchecked(i)) as u64);
+            }
+            if difference > max_dist_u64 {
+                return 0;
+            }
+            i += 1;
+        }
+        1
+    }
+}

src/hex.rs

@@ -0,0 +1,18 @@
+use crate::HEX_LOOKUP;
+
+/// Branchless hex character to nibble conversion using lookup table
+/// Returns 0xFF for invalid characters
+#[inline(always)]
+pub(crate) fn hex_char_to_nibble(c: u8) -> u8 {
+    // SAFETY: c is u8, so always in bounds of 256-element table
+    unsafe { *HEX_LOOKUP.get_unchecked(c as usize) }
+}
+
+/// Convert a hex character to its numeric value (0-15)
+/// Returns None if the character is not a valid hex digit
+#[inline(always)]
+#[allow(dead_code)]
+pub(crate) fn hex_char_to_val(c: u8) -> Option<u8> {
+    let val = hex_char_to_nibble(c);
+    if val == 0xFF { None } else { Some(val) }
+}