test: add per-module unit tests

- hex.rs: nibble parsing for digits, upper, lower, invalid, boundary chars
- classic.rs: popcnt64, string/bytes classic with various sizes and max_dist
- native.rs: popcnt64 vs count_ones, agreement with classic across sizes
- neon_simd.rs: NEON string 16/64 chars, pack path, invalid chars, vs classic
- api.rs: set_algorithm, bytes_within_dist, array first/best/all, error cases

40 unit tests + 2 doc tests, up from 8 + 2.

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

Author: mrecachinas

src/api.rs

@@ -228,3 +228,70 @@ pub fn set_algorithm(algo_name: &str) -> Result<(), &'static str> {
         _ => Err("unknown algorithm"),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn set_algorithm_classic_and_native() {
+        set_algorithm("classic").unwrap();
+        assert_eq!(hex_hamming_distance("deadbeef", "00000000").unwrap(), 24);
+        set_algorithm("native").unwrap();
+        assert_eq!(hex_hamming_distance("deadbeef", "00000000").unwrap(), 24);
+    }
+
+    #[test]
+    fn set_algorithm_unknown() {
+        assert!(set_algorithm("bogus").is_err());
+    }
+
+    #[test]
+    fn bytes_within_dist_basic() {
+        assert_eq!(bytes_within_dist(b"\xff", b"\xfe", 2).unwrap(), true);
+        assert_eq!(bytes_within_dist(b"\xff", b"\x00", 2).unwrap(), false);
+    }
+
+    #[test]
+    fn bytes_within_dist_errors() {
+        assert!(bytes_within_dist(b"", b"\xff", 1).is_err());
+        assert!(bytes_within_dist(b"\xff", b"\xff\x00", 1).is_err());
+    }
+
+    #[test]
+    fn array_first_within_dist_test() {
+        let big = b"\xaa\xbb\xcc\xff";
+        let small = b"\xff";
+        // \xaa vs \xff = dist 4, within max_dist 4
+        assert_eq!(bytes_array_first_within_dist(big, small, 4).unwrap(), Some(0));
+        // Only exact match at index 3
+        assert_eq!(bytes_array_first_within_dist(big, small, 0).unwrap(), Some(3));
+        // dist(\x00, \xff) = 8, exceeds max_dist 1
+        assert_eq!(bytes_array_first_within_dist(b"\x00", b"\xff", 1).unwrap(), None);
+    }
+
+    #[test]
+    fn array_best_within_dist() {
+        // \xfe is distance 1 from \xff, \xaa is distance 4
+        let big = b"\xaa\xfe\xff";
+        let small = b"\xff";
+        let result = bytes_array_best_within_dist(big, small, 8).unwrap();
+        assert_eq!(result, Some((0, 2))); // exact match at index 2
+    }
+
+    #[test]
+    fn array_all_within_dist() {
+        let big = b"\xaa\xfe\xff";
+        let small = b"\xff";
+        let result = bytes_array_all_within_dist(big, small, 8).unwrap();
+        assert_eq!(result.len(), 3);
+        // Last entry should be exact match
+        assert_eq!(result[2], (0, 2));
+    }
+
+    #[test]
+    fn array_errors() {
+        assert!(bytes_array_first_within_dist(b"\xff", b"", 1).is_err()); // empty small
+        assert!(bytes_array_first_within_dist(b"\xaa\xbb\xcc", b"\xff\xff", 1).is_err()); // not a multiple
+    }
+}

src/classic.rs

@@ -146,3 +146,68 @@ pub(crate) fn hamming_distance_bytes_classic(a: &[u8], b: &[u8], max_dist: i64)
         1
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn popcnt64_known_values() {
+        assert_eq!(popcnt64_classic(0), 0);
+        assert_eq!(popcnt64_classic(1), 1);
+        assert_eq!(popcnt64_classic(0xFF), 8);
+        assert_eq!(popcnt64_classic(0xFFFFFFFFFFFFFFFF), 64);
+        assert_eq!(popcnt64_classic(0xAAAAAAAAAAAAAAAA), 32);
+        assert_eq!(popcnt64_classic(0xDEADBEEF), 24);
+    }
+
+    #[test]
+    fn string_classic_basic() {
+        assert_eq!(hamming_distance_string_classic(b"ff", b"00").unwrap(), 8);
+        assert_eq!(hamming_distance_string_classic(b"deadbeef", b"00000000").unwrap(), 24);
+        assert_eq!(hamming_distance_string_classic(b"0000", b"0000").unwrap(), 0);
+    }
+
+    #[test]
+    fn string_classic_invalid() {
+        assert!(hamming_distance_string_classic(b"zz", b"00").is_err());
+        assert!(hamming_distance_string_classic(b"gg", b"00").is_err());
+    }
+
+    #[test]
+    fn string_classic_odd_length() {
+        assert_eq!(hamming_distance_string_classic(b"f", b"0").unwrap(), 4);
+        assert_eq!(hamming_distance_string_classic(b"fff", b"000").unwrap(), 12);
+        assert_eq!(hamming_distance_string_classic(b"fffff", b"00000").unwrap(), 20);
+    }
+
+    #[test]
+    fn bytes_classic_full_distance() {
+        assert_eq!(hamming_distance_bytes_classic(b"\xff", b"\x00", -1), 8);
+        assert_eq!(hamming_distance_bytes_classic(b"\x00\x00", b"\x00\x00", -1), 0);
+        // 64 bytes to exercise 32-byte unrolled loop
+        let a = vec![0xFFu8; 64];
+        let b = vec![0x00u8; 64];
+        assert_eq!(hamming_distance_bytes_classic(&a, &b, -1), 512);
+    }
+
+    #[test]
+    fn bytes_classic_with_max_dist() {
+        // Within threshold → returns 1
+        assert_eq!(hamming_distance_bytes_classic(b"\xff", b"\xfe", 2), 1);
+        // Exceeds threshold → returns 0
+        assert_eq!(hamming_distance_bytes_classic(b"\xff", b"\x00", 2), 0);
+    }
+
+    #[test]
+    fn bytes_classic_tail_bytes() {
+        // 9 bytes: exercises 8-byte chunk + 1 tail byte
+        let a = vec![0xFF; 9];
+        let b = vec![0x00; 9];
+        assert_eq!(hamming_distance_bytes_classic(&a, &b, -1), 72);
+        // 7 bytes: no 8-byte chunks, all tail
+        let a = vec![0xFF; 7];
+        let b = vec![0x00; 7];
+        assert_eq!(hamming_distance_bytes_classic(&a, &b, -1), 56);
+    }
+}

src/hex.rs

@@ -16,3 +16,53 @@ 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) }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn nibble_digits() {
+        for (i, c) in b"0123456789".iter().enumerate() {
+            assert_eq!(hex_char_to_nibble(*c), i as u8);
+        }
+    }
+
+    #[test]
+    fn nibble_upper() {
+        for (i, c) in b"ABCDEF".iter().enumerate() {
+            assert_eq!(hex_char_to_nibble(*c), 10 + i as u8);
+        }
+    }
+
+    #[test]
+    fn nibble_lower() {
+        for (i, c) in b"abcdef".iter().enumerate() {
+            assert_eq!(hex_char_to_nibble(*c), 10 + i as u8);
+        }
+    }
+
+    #[test]
+    fn nibble_invalid() {
+        assert_eq!(hex_char_to_nibble(b'g'), 0xFF);
+        assert_eq!(hex_char_to_nibble(b'z'), 0xFF);
+        assert_eq!(hex_char_to_nibble(b'@'), 0xFF);
+        assert_eq!(hex_char_to_nibble(b' '), 0xFF);
+        assert_eq!(hex_char_to_nibble(b'/'), 0xFF);
+        assert_eq!(hex_char_to_nibble(b':'), 0xFF); // just past '9'
+        assert_eq!(hex_char_to_nibble(b'G'), 0xFF); // just past 'F'
+    }
+
+    #[test]
+    fn hex_val_valid() {
+        assert_eq!(hex_char_to_val(b'0'), Some(0));
+        assert_eq!(hex_char_to_val(b'f'), Some(15));
+        assert_eq!(hex_char_to_val(b'A'), Some(10));
+    }
+
+    #[test]
+    fn hex_val_invalid() {
+        assert_eq!(hex_char_to_val(b'z'), None);
+        assert_eq!(hex_char_to_val(b' '), None);
+    }
+}

src/native.rs

@@ -80,3 +80,47 @@ pub(crate) fn hamming_distance_bytes_native(a: &[u8], b: &[u8], max_dist: i64) -
         1
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn popcnt64_matches_count_ones() {
+        // Verify native matches std count_ones for various values
+        for x in [0u64, 1, 0xFF, 0xDEADBEEF, 0xFFFFFFFFFFFFFFFF, 0x123456789ABCDEF0] {
+            assert_eq!(popcnt64_native(x), x.count_ones() as u64);
+        }
+    }
+
+    #[test]
+    fn bytes_native_full_distance() {
+        assert_eq!(hamming_distance_bytes_native(b"\xff", b"\x00", -1), 8);
+        assert_eq!(hamming_distance_bytes_native(b"\x00\x00", b"\x00\x00", -1), 0);
+        // 64 bytes to exercise 32-byte unrolled loop
+        let a = vec![0xFFu8; 64];
+        let b = vec![0x00u8; 64];
+        assert_eq!(hamming_distance_bytes_native(&a, &b, -1), 512);
+    }
+
+    #[test]
+    fn bytes_native_with_max_dist() {
+        assert_eq!(hamming_distance_bytes_native(b"\xff", b"\xfe", 2), 1);
+        assert_eq!(hamming_distance_bytes_native(b"\xff", b"\x00", 2), 0);
+    }
+
+    #[test]
+    fn bytes_native_agrees_with_classic() {
+        use crate::classic::hamming_distance_bytes_classic;
+        // Test various sizes to cover all loop paths
+        for size in [1, 7, 8, 9, 15, 16, 31, 32, 33, 63, 64, 127] {
+            let a: Vec<u8> = (0..size).map(|i| i as u8).collect();
+            let b: Vec<u8> = (0..size).map(|i| (i as u8).wrapping_add(1)).collect();
+            assert_eq!(
+                hamming_distance_bytes_native(&a, &b, -1),
+                hamming_distance_bytes_classic(&a, &b, -1),
+                "mismatch at size {size}"
+            );
+        }
+    }
+}

src/neon_simd.rs

@@ -237,3 +237,81 @@ pub unsafe fn hamming_distance_string_neon_pack(a: &[u8], b: &[u8]) -> Result<u6
 
     Ok(difference)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn neon_string_basic() {
+        unsafe {
+            assert_eq!(hamming_distance_string_neon(b"deadbeef", b"00000000").unwrap(), 24);
+            assert_eq!(hamming_distance_string_neon(b"ffff", b"0000").unwrap(), 16);
+            assert_eq!(hamming_distance_string_neon(b"0000", b"0000").unwrap(), 0);
+        }
+    }
+
+    #[test]
+    fn neon_string_16_chars() {
+        // Exactly 16 chars — one NEON iteration, no tail
+        unsafe {
+            let a = "f".repeat(16);
+            let b = "0".repeat(16);
+            assert_eq!(hamming_distance_string_neon(a.as_bytes(), b.as_bytes()).unwrap(), 64);
+        }
+    }
+
+    #[test]
+    fn neon_string_64_chars() {
+        // 64 chars — exercises the batched 4×16 loop
+        unsafe {
+            let a = "f".repeat(64);
+            let b = "0".repeat(64);
+            assert_eq!(hamming_distance_string_neon(a.as_bytes(), b.as_bytes()).unwrap(), 256);
+        }
+    }
+
+    #[test]
+    fn neon_string_invalid() {
+        unsafe {
+            assert!(hamming_distance_string_neon(b"zzzzzzzzzzzzzzzz", b"0000000000000000").is_err());
+            assert!(hamming_distance_string_neon(b"@@@@@@@@@@@@@@@@", b"0000000000000000").is_err());
+        }
+    }
+
+    #[test]
+    fn neon_pack_basic() {
+        unsafe {
+            let a = "f".repeat(32);
+            let b = "0".repeat(32);
+            assert_eq!(hamming_distance_string_neon_pack(a.as_bytes(), b.as_bytes()).unwrap(), 128);
+        }
+    }
+
+    #[test]
+    fn neon_pack_with_tail() {
+        // 48 chars: 32-char pack loop + 16-char NEON tail
+        unsafe {
+            let a = "f".repeat(48);
+            let b = "0".repeat(48);
+            assert_eq!(hamming_distance_string_neon_pack(a.as_bytes(), b.as_bytes()).unwrap(), 192);
+        }
+    }
+
+    #[test]
+    fn neon_agrees_with_classic() {
+        use crate::classic::hamming_distance_string_classic;
+        let a = "0123456789abcdef".repeat(8); // 128 chars
+        let b = "fedcba9876543210".repeat(8);
+        unsafe {
+            assert_eq!(
+                hamming_distance_string_neon(a.as_bytes(), b.as_bytes()).unwrap(),
+                hamming_distance_string_classic(a.as_bytes(), b.as_bytes()).unwrap()
+            );
+            assert_eq!(
+                hamming_distance_string_neon_pack(a.as_bytes(), b.as_bytes()).unwrap(),
+                hamming_distance_string_classic(a.as_bytes(), b.as_bytes()).unwrap()
+            );
+        }
+    }
+}