gh-118184: Support tuples for find, index, rfind & rindex

Doc/library/stdtypes.rst

@@ -1724,8 +1724,9 @@ expression support in the :mod:`re` module).
 .. method:: str.find(sub[, start[, end]])
 
    Return the lowest index in the string where substring *sub* is found within
-   the slice ``s[start:end]``.  Optional arguments *start* and *end* are
-   interpreted as in slice notation.  Return ``-1`` if *sub* is not found.
+   the slice ``s[start:end]``.  *sub* can also be a tuple of substrings to look
+   for.  Optional arguments *start* and *end* are interpreted as in slice
+   notation.  Return ``-1`` if *sub* is not found.
 
    .. note::
 
@@ -1736,6 +1737,9 @@ expression support in the :mod:`re` module).
          >>> 'Py' in 'Python'
          True
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of substrings.
+
 
 .. method:: str.format(*args, **kwargs)
 
@@ -2030,8 +2034,12 @@ expression support in the :mod:`re` module).
 .. method:: str.rfind(sub[, start[, end]])
 
    Return the highest index in the string where substring *sub* is found, such
-   that *sub* is contained within ``s[start:end]``.  Optional arguments *start*
-   and *end* are interpreted as in slice notation.  Return ``-1`` on failure.
+   that *sub* is contained within ``s[start:end]``.  *sub* can also be a tuple
+   of substrings to look for.  Optional arguments *start* and *end* are
+   interpreted as in slice notation.  Return ``-1`` on failure.
+
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of substrings.
 
 
 .. method:: str.rindex(sub[, start[, end]])
@@ -2859,9 +2867,10 @@ arbitrary binary data.
             bytearray.find(sub[, start[, end]])
 
    Return the lowest index in the data where the subsequence *sub* is found,
-   such that *sub* is contained in the slice ``s[start:end]``.  Optional
-   arguments *start* and *end* are interpreted as in slice notation.  Return
-   ``-1`` if *sub* is not found.
+   such that *sub* is contained in the slice ``s[start:end]``.  *sub* can
+   also be a tuple of subsequences to look for.  Optional arguments *start*
+   and *end* are interpreted as in slice notation.  Return ``-1`` if *sub*
+   is not found.
 
    The subsequence to search for may be any :term:`bytes-like object` or an
    integer in the range 0 to 255.
@@ -2878,6 +2887,9 @@ arbitrary binary data.
    .. versionchanged:: 3.3
       Also accept an integer in the range 0 to 255 as the subsequence.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of subsequences.
+
 
 .. method:: bytes.index(sub[, start[, end]])
             bytearray.index(sub[, start[, end]])
@@ -2947,16 +2959,19 @@ arbitrary binary data.
             bytearray.rfind(sub[, start[, end]])
 
    Return the highest index in the sequence where the subsequence *sub* is
-   found, such that *sub* is contained within ``s[start:end]``.  Optional
-   arguments *start* and *end* are interpreted as in slice notation. Return
-   ``-1`` on failure.
+   found, such that *sub* is contained within ``s[start:end]``.  *sub* can
+   also be a tuple of subsequences to look for.  Optional arguments *start*
+   and *end* are interpreted as in slice notation.  Return ``-1`` on failure.
 
    The subsequence to search for may be any :term:`bytes-like object` or an
    integer in the range 0 to 255.
 
    .. versionchanged:: 3.3
       Also accept an integer in the range 0 to 255 as the subsequence.
 
+   .. versionchanged:: 3.14
+      *sub* can now be a tuple of subsequences.
+
 
 .. method:: bytes.rindex(sub[, start[, end]])
             bytearray.rindex(sub[, start[, end]])

Lib/test/string_tests.py

@@ -217,6 +217,19 @@ def test_find(self):
                 if loc != -1:
                     self.assertEqual(i[loc:loc+len(j)], j)
 
+        # test tuple arguments
+        self.checkequal(2, '__aa__bb__', 'find', ('aa', 'bb'))
+        self.checkequal(2, '__aa__bb__', 'find', ('bb', 'aa'))
+        self.checkequal(-1, '__aa__bb__', 'find', ('cc', 'dd'))
+        self.checkequal(-1, '__aa__bb__', 'find', ())
+        self.checkequal(6, '__aa__bb__', 'find', ('aa', 'bb'), 3)
+        self.checkequal(-1, '__aa__bb__', 'find', ('aa', 'cc'), 3)
+        self.checkequal(2, '__aa__bb__', 'find', ('aa', 'bb'), 0, 10)
+        self.checkequal(-1, '__aa__bb__', 'find', ('aa', 'bb'), 0, 3)
+        self.checkequal(2, '__aa__bb__', 'find', ('aa', 'bb'), 0, 4)
+
+        self.checkraises(TypeError, 'hello', 'find', (42,))
+
     def test_rfind(self):
         self.checkequal(9,  'abcdefghiabc', 'rfind', 'abc')
         self.checkequal(12, 'abcdefghiabc', 'rfind', '')
@@ -270,6 +283,18 @@ def test_rfind(self):
         # issue #15534
         self.checkequal(0, '<......\u043c...', "rfind", "<")
 
+        # test tuple arguments
+        self.checkequal(6, '__aa__bb__', 'rfind', ('aa', 'bb'))
+        self.checkequal(6, '__aa__bb__', 'rfind', ('bb', 'aa'))
+        self.checkequal(-1, '__aa__bb__', 'rfind', ('cc', 'dd'))
+        self.checkequal(-1, '__aa__bb__', 'rfind', ())
+        self.checkequal(-1, '__aa__bb__', 'rfind', ('aa', 'cc'), 3)
+        self.checkequal(6, '__aa__bb__', 'rfind', ('aa', 'bb'), 0, 10)
+        self.checkequal(-1, '__aa__bb__', 'rfind', ('aa', 'bb'), 7, 10)
+        self.checkequal(6, '__aa__bb__', 'rfind', ('aa', 'bb'), 6, 10)
+
+        self.checkraises(TypeError, 'hello', 'rfind', (42,))
+
     def test_index(self):
         self.checkequal(0, 'abcdefghiabc', 'index', '')
         self.checkequal(3, 'abcdefghiabc', 'index', 'def')

Misc/NEWS.d/next/Core and Builtins/2024-05-24-11-07-16.gh-issue-118184.EK4di_.rst

@@ -0,0 +1 @@
+Support tuples for :meth:`str.find`, :meth:`bytearray.find`, :meth:`bytes.find`, :meth:`str.rfind`, :meth:`bytearray.rfind` and :meth:`bytes.rfind`.

Objects/bytes_methods.c

@@ -557,10 +557,26 @@ find_internal(const char *str, Py_ssize_t len,
 }
 
 PyObject *
-_Py_bytes_find(const char *str, Py_ssize_t len, PyObject *sub,
+_Py_bytes_find(const char *str, Py_ssize_t len, PyObject *subobj,
                Py_ssize_t start, Py_ssize_t end)
 {
-    Py_ssize_t result = find_internal(str, len, "find", sub, start, end, +1);
+    Py_ssize_t result;
+    if (PyTuple_Check(subobj)) {
+        result = -1;
+        for (Py_ssize_t i = 0; i < PyTuple_GET_SIZE(subobj); i++) {
+            PyObject *subseq = PyTuple_GET_ITEM(subobj, i);
+            Py_ssize_t new_result = find_internal(str, len, "find", subseq,
+                                                  start, end, +1);
+            if (new_result == -2) {
+                return NULL;
+            }
+            if (new_result != -1 && (new_result < result || result == -1)) {
+                result = new_result;
+            }
+        }
+        return PyLong_FromSsize_t(result);
+    }
+    result = find_internal(str, len, "find", subobj, start, end, +1);
     if (result == -2)
         return NULL;
     return PyLong_FromSsize_t(result);
@@ -582,10 +598,26 @@ _Py_bytes_index(const char *str, Py_ssize_t len, PyObject *sub,
 }
 
 PyObject *
-_Py_bytes_rfind(const char *str, Py_ssize_t len, PyObject *sub,
+_Py_bytes_rfind(const char *str, Py_ssize_t len, PyObject *subobj,
                 Py_ssize_t start, Py_ssize_t end)
 {
-    Py_ssize_t result = find_internal(str, len, "rfind", sub, start, end, -1);
+    Py_ssize_t result;
+    if (PyTuple_Check(subobj)) {
+        result = -1;
+        for (Py_ssize_t i = 0; i < PyTuple_GET_SIZE(subobj); i++) {
+            PyObject *subseq = PyTuple_GET_ITEM(subobj, i);
+            Py_ssize_t new_result = find_internal(str, len, "rfind", subseq,
+                                                  start, end, -1);
+            if (new_result == -2) {
+                return NULL;
+            }
+            if (new_result > result) {
+                result = new_result;
+            }
+        }
+        return PyLong_FromSsize_t(result);
+    }
+    result = find_internal(str, len, "rfind", subobj, start, end, -1);
     if (result == -2)
         return NULL;
     return PyLong_FromSsize_t(result);

Objects/unicodeobject.c

@@ -11334,7 +11334,13 @@ unicode_expandtabs_impl(PyObject *self, int tabsize)
 }
 
 /*[clinic input]
-str.find as unicode_find = str.count
+str.find as unicode_find -> Py_ssize_t
+
+    self as str: self
+    sub as subobj: object
+    start: slice_index(accept={int, NoneType}, c_default='0') = None
+    end: slice_index(accept={int, NoneType}, c_default='PY_SSIZE_T_MAX') = None
+    /
 
 Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
 
@@ -11343,11 +11349,36 @@ Return -1 on failure.
 [clinic start generated code]*/
 
 static Py_ssize_t
-unicode_find_impl(PyObject *str, PyObject *substr, Py_ssize_t start,
+unicode_find_impl(PyObject *str, PyObject *subobj, Py_ssize_t start,
                   Py_ssize_t end)
-/*[clinic end generated code: output=51dbe6255712e278 input=4a89d2d68ef57256]*/
+/*[clinic end generated code: output=80175735a6d549d0 input=51e7b530950ab304]*/
 {
-    Py_ssize_t result = any_find_slice(str, substr, start, end, 1);
+    Py_ssize_t result;
+    if (PyTuple_Check(subobj)) {
+        result = -1;
+        for (Py_ssize_t i = 0; i < PyTuple_GET_SIZE(subobj); i++) {
+            PyObject *substr = PyTuple_GET_ITEM(subobj, i);
+            if (!PyUnicode_Check(substr)) {
+                PyErr_Format(PyExc_TypeError,
+                             "tuple for find must only contain str, "
+                             "not %.100s",
+                             Py_TYPE(substr)->tp_name);
+                return -1;
+            }
+            Py_ssize_t new_result = any_find_slice(str, substr, start, end, 1);
+            if (new_result != -1 && (new_result < result || result == -1)) {
+                result = new_result;
+            }
+        }
+        return result;
+    }
+    if (!PyUnicode_Check(subobj)) {
+        PyErr_Format(PyExc_TypeError,
+                     "find first arg must be str or "
+                     "a tuple of str, not %.100s", Py_TYPE(subobj)->tp_name);
+        return -1;
+    }
+    result = any_find_slice(str, subobj, start, end, 1);
     if (result < 0) {
         return -1;
     }
@@ -12496,7 +12527,7 @@ unicode_repr(PyObject *unicode)
 }
 
 /*[clinic input]
-str.rfind as unicode_rfind = str.count
+str.rfind as unicode_rfind = str.find
 
 Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
 
@@ -12505,11 +12536,36 @@ Return -1 on failure.
 [clinic start generated code]*/
 
 static Py_ssize_t
-unicode_rfind_impl(PyObject *str, PyObject *substr, Py_ssize_t start,
+unicode_rfind_impl(PyObject *str, PyObject *subobj, Py_ssize_t start,
                    Py_ssize_t end)
-/*[clinic end generated code: output=880b29f01dd014c8 input=898361fb71f59294]*/
+/*[clinic end generated code: output=9d316eee7b9f9bf0 input=23ae7964e8f70b35]*/
 {
-    Py_ssize_t result = any_find_slice(str, substr, start, end, -1);
+    Py_ssize_t result;
+    if (PyTuple_Check(subobj)) {
+        result = -1;
+        for (Py_ssize_t i = 0; i < PyTuple_GET_SIZE(subobj); i++) {
+            PyObject *substr = PyTuple_GET_ITEM(subobj, i);
+            if (!PyUnicode_Check(substr)) {
+                PyErr_Format(PyExc_TypeError,
+                             "tuple for rfind must only contain str, "
+                             "not %.100s",
+                             Py_TYPE(substr)->tp_name);
+                return -1;
+            }
+            Py_ssize_t new_result = any_find_slice(str, substr, start, end, -1);
+            if (new_result > result) {
+                result = new_result;
+            }
+        }
+        return result;
+    }
+    if (!PyUnicode_Check(subobj)) {
+        PyErr_Format(PyExc_TypeError,
+                     "rfind first arg must be str or "
+                     "a tuple of str, not %.100s", Py_TYPE(subobj)->tp_name);
+        return -1;
+    }
+    result = any_find_slice(str, subobj, start, end, -1);
     if (result < 0) {
         return -1;
     }