[REVIEW] Add .str.find_multiple API

docs/cudf/source/api_docs/string_handling.rst

@@ -28,6 +28,7 @@ strings and apply several methods to it. These can be accessed like
    filter_tokens
    find
    findall
+   find_multiple
    get
    get_json_object
    hex_to_int

python/cudf/cudf/_lib/strings/__init__.py

@@ -61,6 +61,7 @@
     startswith,
     startswith_multiple,
 )
+from cudf._lib.strings.find_multiple import find_multiple
 from cudf._lib.strings.findall import findall
 from cudf._lib.strings.json import GetJsonObjectOptions, get_json_object
 from cudf._lib.strings.padding import (

python/cudf/cudf/core/column/string.py

@@ -3623,6 +3623,54 @@ def findall(self, pat: str, flags: int = 0) -> SeriesOrIndex:
         data = libstrings.findall(self._column, pat, flags)
         return self._return_or_inplace(data)
 
+    def find_multiple(self, patterns: SeriesOrIndex) -> SeriesOrIndex:
+        """
+        Find all first occurrences of patterns in the Series/Index.
+
+        Parameters
+        ----------
+        patterns : Series of Index
+            Patters to search for in the given Series/Index.
+
+        Returns
+        -------
+        Series
+            A Series with a list of all indices
+            if the pattern's first occurrence.
+            -1 if a pattern is not found.
+
+        Examples
+        --------
+        >>> import cudf
+        >>> s = cudf.Series(["strings", "to", "search", "in"])
+        >>> s
+        0    strings
+        1         to
+        2     search
+        3         in
+        dtype: object
+        >>> t = cudf.Series(["a", "s", "g", "i", "o", "r"])
+        >>> s.str.find_multiple(t)
+        0       [-1, 0, 5, 3, -1, 2]
+        1    [-1, -1, -1, -1, 1, -1]
+        2      [2, 0, -1, -1, -1, 3]
+        3    [-1, -1, -1, 0, -1, -1]
+        dtype: list
+        """
+        if not isinstance(patterns, (cudf.Series, cudf.Index)):
+            raise TypeError(
+                "patterns can only be a Series/Index, "
+                f"got: {type(patterns)}"
+            )
+
+        return cudf.Series(
+            libstrings.find_multiple(self._column, patterns._column),
+            index=self._parent.index
+            if isinstance(self._parent, cudf.Series)
+            else self._parent,
+            name=self._parent.name,
+        )
+
     def isempty(self) -> SeriesOrIndex:
         """
         Check whether each string is an empty string.

python/cudf/cudf/tests/test_string.py

@@ -3423,3 +3423,37 @@ def test_str_join_lists(sr, sep, string_na_rep, sep_na_rep, expected):
         sep=sep, string_na_rep=string_na_rep, sep_na_rep=sep_na_rep
     )
     assert_eq(actual, expected)
+
+
+def test_str_find_multiple():
+    s = cudf.Series(["strings", "to", "search", "in"])
+    t = cudf.Series(["a", "s", "g", "i", "o", "r"])
+
+    expected = cudf.Series(
+        [
+            [-1, 0, 5, 3, -1, 2],
+            [-1, -1, -1, -1, 1, -1],
+            [2, 0, -1, -1, -1, 3],
+            [-1, -1, -1, 0, -1, -1],
+        ]
+    )
+
+    assert_eq(s.str.find_multiple(t).to_pandas(), expected.to_pandas())
+
+    s = cudf.Index(s)
+    t = cudf.Index(t)
+
+    expected.index = s
+
+    assert_eq(s.str.find_multiple(t).to_pandas(), expected.to_pandas())
+
+
+def test_str_find_multiple_error():
+    s = cudf.Series(["strings", "to", "search", "in"])
+    with pytest.raises(
+        TypeError,
+        match=re.escape(
+            "patterns can only be a Series/Index, got: <class 'str'>"
+        ),
+    ):
+        s.str.find_multiple("a")