Add: Reusable case-insensitive needles with metadata for Rust & C++

Author: ashvardanian

include/stringzilla/stringzilla.hpp

@@ -61,6 +61,8 @@ template <typename>
 class basic_string_slice;
 template <typename, typename>
 class basic_string;
+template <typename>
+class utf8_case_insensitive_needle;
 
 using string_span = basic_string_slice<char>;
 using string_view = basic_string_slice<char const>;
@@ -1664,6 +1666,52 @@ struct concatenation {
 
 #pragma endregion
 
+#pragma region Case-Insensitive Search Pattern
+
+/**
+ *  @brief  Pre-compiled case-insensitive search pattern for UTF-8 strings.
+ *
+ *  Caches metadata for efficient repeated searches with the same needle.
+ *  Useful when searching multiple haystacks for the same pattern.
+ *
+ *  @code{.cpp}
+ *  sz::utf8_case_insensitive_needle pattern("hello");
+ *  for (auto const& haystack : haystacks) {
+ *      auto match = haystack.utf8_case_insensitive_find(pattern);
+ *      if (match) { ... }
+ *  }
+ *  @endcode
+ *
+ *  @tparam char_type_ The character type, usually `char const` or `char`.
+ */
+template <typename char_type_ = char const>
+class utf8_case_insensitive_needle {
+    static_assert(sizeof(char_type_) == 1, "Characters must be a single byte long");
+
+    using char_type = char_type_;
+
+    char_type *needle_;
+    std::size_t length_;
+    mutable sz_utf8_case_insensitive_needle_metadata_t metadata_;
+
+  public:
+    utf8_case_insensitive_needle(char_type *needle, std::size_t length) noexcept
+        : needle_(needle), length_(length), metadata_ {} {}
+
+    utf8_case_insensitive_needle(basic_string_slice<char_type> needle) noexcept
+        : needle_(needle.data()), length_(needle.size()), metadata_ {} {}
+
+    template <std::size_t length_>
+    utf8_case_insensitive_needle(char_type (&needle)[length_]) noexcept
+        : needle_(needle), length_(length_ - 1), metadata_ {} {}
+
+    char_type *data() const noexcept { return needle_; }
+    std::size_t size() const noexcept { return length_; }
+    sz_utf8_case_insensitive_needle_metadata_t const &metadata_ref() const noexcept { return metadata_; }
+};
+
+#pragma endregion
+
 #pragma region String Views and Spans
 
 /**
@@ -2333,6 +2381,21 @@ class basic_string_slice {
         return {static_cast<size_type>(ptr - start_), match_length};
     }
 
+    /**
+     *  @brief Find the byte offset of the first occurrence of a pre-compiled case-insensitive pattern.
+     *  @param[in] needle A pre-compiled pattern with cached metadata for efficient repeated searches.
+     *  @return Match info with offset and length, or @c npos offset if not found.
+     */
+    template <typename needle_char_type_>
+    sized_match_t utf8_case_insensitive_find(
+        utf8_case_insensitive_needle<needle_char_type_> const &needle) const noexcept {
+        sz_size_t match_length = 0;
+        auto ptr = sz_utf8_case_insensitive_find(start_, length_, needle.data(), needle.size(), &needle.metadata_ref(),
+                                                 &match_length);
+        if (!ptr) return {npos, static_cast<size_type>(0)};
+        return {static_cast<size_type>(ptr - start_), match_length};
+    }
+
     /**
      *  @brief Iterate over UTF-8 characters (codepoints) in the string.
      *  @return A range view over UTF-32 codepoints decoded from UTF-8 bytes.

rust/stringzilla.rs

@@ -167,6 +167,74 @@ impl Default for Utf8CaseInsensitiveNeedleMetadata {
     }
 }
 
+/// Pre-compiled case-insensitive search pattern for UTF-8 strings.
+///
+/// Caches metadata for efficient repeated searches with the same needle.
+/// Useful when searching multiple haystacks for the same pattern.
+///
+/// # Examples
+///
+/// ```
+/// use stringzilla::stringzilla::{utf8_case_insensitive_find, Utf8CaseInsensitiveNeedle};
+///
+/// let needle = Utf8CaseInsensitiveNeedle::new(b"hello");
+/// let haystack1 = b"Hello World";
+/// let haystack2 = b"HELLO there";
+///
+/// // Metadata is computed once on first search, reused for subsequent searches
+/// let result1 = utf8_case_insensitive_find(haystack1, &needle);
+/// let result2 = utf8_case_insensitive_find(haystack2, &needle);
+///
+/// assert!(result1.is_some());
+/// assert!(result2.is_some());
+/// ```
+pub struct Utf8CaseInsensitiveNeedle<'a> {
+    needle: &'a [u8],
+    metadata: UnsafeCell<Utf8CaseInsensitiveNeedleMetadata>,
+}
+
+impl<'a> Utf8CaseInsensitiveNeedle<'a> {
+    /// Creates a new pre-compiled case-insensitive needle.
+    ///
+    /// The metadata will be computed lazily on first use.
+    #[inline]
+    pub fn new(needle: &'a [u8]) -> Self {
+        Self {
+            needle,
+            metadata: UnsafeCell::new(Utf8CaseInsensitiveNeedleMetadata::default()),
+        }
+    }
+
+    /// Returns the needle bytes.
+    #[inline]
+    pub fn as_bytes(&self) -> &[u8] {
+        self.needle
+    }
+
+    /// Returns the length of the needle in bytes.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.needle.len()
+    }
+
+    /// Returns true if the needle is empty.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.needle.is_empty()
+    }
+
+    /// Internal: returns a mutable pointer to the metadata for FFI calls.
+    #[inline]
+    pub(crate) fn metadata_ptr(&self) -> *mut Utf8CaseInsensitiveNeedleMetadata {
+        self.metadata.get()
+    }
+}
+
+// Safety: The metadata is only mutated through FFI during search operations,
+// which internally synchronize access. The needle reference is immutable.
+unsafe impl<'a> Send for Utf8CaseInsensitiveNeedle<'a> {}
+unsafe impl<'a> Sync for Utf8CaseInsensitiveNeedle<'a> {}
+
 /// Incremental hasher state for StringZilla's 64-bit hash.
 ///
 /// Use `Hasher::new(seed)` to construct, then call `update(&mut self, data)`
@@ -319,6 +387,7 @@ impl<T: AsRef<[u8]>> From<T> for Byteset {
     }
 }
 
+use core::cell::UnsafeCell;
 use core::cmp::Ordering;
 use core::ffi::{c_char, c_void, CStr};
 use core::fmt::{self, Write};
@@ -994,6 +1063,8 @@ where
 ///
 /// # Examples
 ///
+/// Basic usage with string slices:
+///
 /// ```
 /// use stringzilla::stringzilla as sz;
 /// let haystack = "Hello WORLD";
@@ -1003,32 +1074,87 @@ where
 /// }
 /// ```
 ///
+/// With a pre-compiled needle for repeated searches:
+///
+/// ```
+/// use stringzilla::stringzilla::{utf8_case_insensitive_find, Utf8CaseInsensitiveNeedle};
+///
+/// let needle = Utf8CaseInsensitiveNeedle::new(b"hello");
+///
+/// // Metadata is computed once, reused for subsequent searches
+/// let result1 = utf8_case_insensitive_find(b"Hello World", &needle);
+/// let result2 = utf8_case_insensitive_find(b"HELLO there", &needle);
+///
+/// assert_eq!(result1, Some((0, 5)));
+/// assert_eq!(result2, Some((0, 5)));
+/// ```
+///
 pub fn utf8_case_insensitive_find<H, N>(haystack: H, needle: N) -> Option<(usize, usize)>
 where
     H: AsRef<[u8]>,
-    N: AsRef<[u8]>,
+    N: Utf8CaseInsensitiveNeedleArg,
 {
-    let haystack_ref = haystack.as_ref();
-    let needle_ref = needle.as_ref();
-    let mut matched_length: usize = 0;
+    needle.find_case_insensitive_in(haystack.as_ref())
+}
 
-    let mut needle_metadata = Utf8CaseInsensitiveNeedleMetadata::default();
-    let result = unsafe {
-        sz_utf8_case_insensitive_find(
-            haystack_ref.as_ptr() as *const c_void,
-            haystack_ref.len(),
-            needle_ref.as_ptr() as *const c_void,
-            needle_ref.len(),
-            &mut needle_metadata,
-            &mut matched_length,
-        )
-    };
+/// Trait for types that can be used as a case-insensitive search needle.
+///
+/// This trait is implemented for:
+/// - Any type implementing `AsRef<[u8]>` (strings, byte slices, etc.)
+/// - [`Utf8CaseInsensitiveNeedle`] references for efficient repeated searches
+pub trait Utf8CaseInsensitiveNeedleArg {
+    /// Performs the case-insensitive search in the given haystack.
+    fn find_case_insensitive_in(self, haystack: &[u8]) -> Option<(usize, usize)>;
+}
 
-    if result.is_null() {
-        None
-    } else {
-        let offset = unsafe { result.offset_from(haystack_ref.as_ptr() as *const c_void) };
-        Some((offset as usize, matched_length))
+impl<T: AsRef<[u8]>> Utf8CaseInsensitiveNeedleArg for T {
+    fn find_case_insensitive_in(self, haystack: &[u8]) -> Option<(usize, usize)> {
+        let needle_ref = self.as_ref();
+        let mut matched_length: usize = 0;
+        let mut needle_metadata = Utf8CaseInsensitiveNeedleMetadata::default();
+
+        let result = unsafe {
+            sz_utf8_case_insensitive_find(
+                haystack.as_ptr() as *const c_void,
+                haystack.len(),
+                needle_ref.as_ptr() as *const c_void,
+                needle_ref.len(),
+                &mut needle_metadata,
+                &mut matched_length,
+            )
+        };
+
+        if result.is_null() {
+            None
+        } else {
+            let offset = unsafe { result.offset_from(haystack.as_ptr() as *const c_void) };
+            Some((offset as usize, matched_length))
+        }
+    }
+}
+
+impl<'a, 'b> Utf8CaseInsensitiveNeedleArg for &'b Utf8CaseInsensitiveNeedle<'a> {
+    fn find_case_insensitive_in(self, haystack: &[u8]) -> Option<(usize, usize)> {
+        let needle_bytes = self.as_bytes();
+        let mut matched_length: usize = 0;
+
+        let result = unsafe {
+            sz_utf8_case_insensitive_find(
+                haystack.as_ptr() as *const c_void,
+                haystack.len(),
+                needle_bytes.as_ptr() as *const c_void,
+                needle_bytes.len(),
+                &mut *self.metadata_ptr(),
+                &mut matched_length,
+            )
+        };
+
+        if result.is_null() {
+            None
+        } else {
+            let offset = unsafe { result.offset_from(haystack.as_ptr() as *const c_void) };
+            Some((offset as usize, matched_length))
+        }
     }
 }