[3.12] gh-46236: Document PyUnicode_RSplit, PyUnicode_Partition and PyUnicode_RPartit...

gh-46236: Document PyUnicode_RSplit, PyUnicode_Partition and PyUnicode_RPartition (GH-130191)
(cherry picked from commit 0f5b82169e12321fd2294bf534496ad42a682ac4)

Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 69b58e90478e237369db4540b2b4c1ec0f68c898..3dd3b3a36c2ff54716189b86adbe7b350924e0c1 100644 (file)
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -1376,6 +1376,20 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
    separator.  At most *maxsplit* splits will be done.  If negative, no limit is
    set.  Separators are not included in the resulting list.
 
+   On error, return ``NULL`` with an exception set.
+
+   Equivalent to :py:meth:`str.split`.
+
+
+.. c:function:: PyObject* PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
+
+   Similar to :c:func:`PyUnicode_Split`, but splitting will be done beginning
+   at the end of the string.
+
+   On error, return ``NULL`` with an exception set.
+
+   Equivalent to :py:meth:`str.rsplit`.
+
 
 .. c:function:: PyObject* PyUnicode_Splitlines(PyObject *unicode, int keepends)
 
@@ -1384,6 +1398,33 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
    characters are not included in the resulting strings.
 
 
+.. c:function:: PyObject* PyUnicode_Partition(PyObject *unicode, PyObject *sep)
+
+   Split a Unicode string at the first occurrence of *sep*, and return
+   a 3-tuple containing the part before the separator, the separator itself,
+   and the part after the separator. If the separator is not found,
+   return a 3-tuple containing the string itself, followed by two empty strings.
+
+   *sep* must not be empty.
+
+   On error, return ``NULL`` with an exception set.
+
+   Equivalent to :py:meth:`str.partition`.
+
+
+.. c:function:: PyObject* PyUnicode_RPartition(PyObject *unicode, PyObject *sep)
+
+   Similar to :c:func:`PyUnicode_Partition`, but split a Unicode string at the
+   last occurrence of *sep*. If the separator is not found, return a 3-tuple
+   containing two empty strings, followed by the string itself.
+
+   *sep* must not be empty.
+
+   On error, return ``NULL`` with an exception set.
+
+   Equivalent to :py:meth:`str.rpartition`.
+
+
 .. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
 
    Join a sequence of strings using the given *separator* and return the resulting

diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 509de0560e933338b7cc34eaa7e46bdcf8d977be..fb1215df777644d9516c81d20818c21c0066b42b 100644 (file)
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -2640,13 +2640,26 @@ PyUnicode_Concat:PyObject*::+1:
 PyUnicode_Concat:PyObject*:left:0:
 PyUnicode_Concat:PyObject*:right:0:
 
+PyUnicode_Partition:PyObject*::+1:
+PyUnicode_Partition:PyObject*:unicode:0:
+PyUnicode_Partition:PyObject*:sep:0:
+
+PyUnicode_RPartition:PyObject*::+1:
+PyUnicode_RPartition:PyObject*:unicode:0:
+PyUnicode_RPartition:PyObject*:sep:0:
+
+PyUnicode_RSplit:PyObject*::+1:
+PyUnicode_RSplit:PyObject*:unicode:0:
+PyUnicode_RSplit:PyObject*:sep:0:
+PyUnicode_RSplit:Py_ssize_t:maxsplit::
+
 PyUnicode_Split:PyObject*::+1:
-PyUnicode_Split:PyObject*:left:0:
-PyUnicode_Split:PyObject*:right:0:
+PyUnicode_Split:PyObject*:unicode:0:
+PyUnicode_Split:PyObject*:sep:0:
 PyUnicode_Split:Py_ssize_t:maxsplit::
 
 PyUnicode_Splitlines:PyObject*::+1:
-PyUnicode_Splitlines:PyObject*:s:0:
+PyUnicode_Splitlines:PyObject*:unicode:0:
 PyUnicode_Splitlines:int:keepend::
 
 PyUnicode_Translate:PyObject*::+1:

diff --git a/Misc/NEWS.d/next/Documentation/2025-02-16-14-57-00.gh-issue-46236.2HuS4S.rst b/Misc/NEWS.d/next/Documentation/2025-02-16-14-57-00.gh-issue-46236.2HuS4S.rst
new file mode 100644 (file)
index 0000000..0fc31a5
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2025-02-16-14-57-00.gh-issue-46236.2HuS4S.rst
@@ -0,0 +1,2 @@
+C API: Document :c:func:`PyUnicode_RSplit`, :c:func:`PyUnicode_Partition` and
+:c:func:`PyUnicode_RPartition`.