From 4f7f4522a5615290ced9ec29adc378519408d403 Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Sun, 16 Feb 2025 14:57:45 +0100 Subject: [PATCH 1/8] gh-46236: Document PyUnicode_RSplit, PyUnicode_Partition and PyUnicode_RPartition --- Doc/c-api/unicode.rst | 21 +++++++++++++++++++ ...5-02-16-14-57-00.gh-issue-46236.2HuS4S.rst | 2 ++ 2 files changed, 23 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2025-02-16-14-57-00.gh-issue-46236.2HuS4S.rst diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 8f383cd6c4015f..9d976c12b50851 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1399,6 +1399,12 @@ They all return ``NULL`` or ``-1`` if an exception occurs. set. Separators are not included in the resulting list. +.. 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. + + .. c:function:: PyObject* PyUnicode_Splitlines(PyObject *unicode, int keepends) Split a Unicode string at line breaks, returning a list of Unicode strings. @@ -1406,6 +1412,21 @@ 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 the 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. + + +.. c:function:: PyObject* PyUnicode_RPartition(PyObject *unicode, PyObject *sep) + + Similar to :c:func:`PyUnicode_Partition`, but split the 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. + + .. 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/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 index 00000000000000..6570e0661443a2 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-02-16-14-57-00.gh-issue-46236.2HuS4S.rst @@ -0,0 +1,2 @@ +Document :c:func:`PyUnicode_RSplit`, :c:func:`PyUnicode_Partition` and +:c:func:`PyUnicode_RPartition`. From f76e1af30ff9ea9d882bc7590baee0b02b988c97 Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Sun, 16 Feb 2025 15:18:26 +0100 Subject: [PATCH 2/8] Add refcounts data --- Doc/data/refcounts.dat | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index a483c57cb2ce06..7f576d21ff489d 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -2655,13 +2655,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: From c19f46c5743454f1bd25e1045e899f2cd71fd34a Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Sun, 16 Feb 2025 15:55:11 +0100 Subject: [PATCH 3/8] Review --- Doc/c-api/unicode.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 9d976c12b50851..a5936eddfecc9b 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1414,17 +1414,17 @@ They all return ``NULL`` or ``-1`` if an exception occurs. .. c:function:: PyObject* PyUnicode_Partition(PyObject *unicode, PyObject *sep) - Split the 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. + Split the 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. .. c:function:: PyObject* PyUnicode_RPartition(PyObject *unicode, PyObject *sep) - Similar to :c:func:`PyUnicode_Partition`, but split the 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. + 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. .. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq) From 0e52d8dc4e576b7e50e453fb6e0319acb916bfad Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Sun, 16 Feb 2025 16:43:52 +0100 Subject: [PATCH 4/8] Suggestion --- Doc/c-api/unicode.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index a5936eddfecc9b..bf5c829da90757 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1414,10 +1414,10 @@ They all return ``NULL`` or ``-1`` if an exception occurs. .. c:function:: PyObject* PyUnicode_Partition(PyObject *unicode, PyObject *sep) - Split the 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. + Split the 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. .. c:function:: PyObject* PyUnicode_RPartition(PyObject *unicode, PyObject *sep) From f02d59962ca5eda67a7f75d3237eb25a0a21d1a2 Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Mon, 17 Feb 2025 11:37:53 +0100 Subject: [PATCH 5/8] Suggestion --- Doc/c-api/unicode.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index bf5c829da90757..2c19afa10ef768 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1414,7 +1414,7 @@ They all return ``NULL`` or ``-1`` if an exception occurs. .. c:function:: PyObject* PyUnicode_Partition(PyObject *unicode, PyObject *sep) - Split the Unicode string at the first occurrence of *sep*, and return + 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. From 94dc538e38477976b2e879d980d50f36f816c83d Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Mon, 17 Feb 2025 16:52:54 +0100 Subject: [PATCH 6/8] Review --- Doc/c-api/unicode.rst | 4 +++- .../2025-02-16-14-57-00.gh-issue-46236.2HuS4S.rst | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 2c19afa10ef768..26612d26b3c5ba 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1418,13 +1418,15 @@ They all return ``NULL`` or ``-1`` if an exception occurs. 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. .. 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. + containing two empty strings, followed by the string itself. *sep* must + not be empty. .. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq) 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 index 6570e0661443a2..0fc31a51be55f5 100644 --- 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 @@ -1,2 +1,2 @@ -Document :c:func:`PyUnicode_RSplit`, :c:func:`PyUnicode_Partition` and +C API: Document :c:func:`PyUnicode_RSplit`, :c:func:`PyUnicode_Partition` and :c:func:`PyUnicode_RPartition`. From 0b2d9bb1dcfce5f5b1434de34cc6520eea8ed6d4 Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Mon, 17 Feb 2025 17:05:04 +0100 Subject: [PATCH 7/8] Add newlines --- Doc/c-api/unicode.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 26612d26b3c5ba..0eff4040bba785 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1418,6 +1418,7 @@ They all return ``NULL`` or ``-1`` if an exception occurs. 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. @@ -1425,8 +1426,9 @@ They all return ``NULL`` or ``-1`` if an exception occurs. 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. + containing two empty strings, followed by the string itself. + + *sep* must not be empty. .. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq) From 0957364e5a20f77ca3b690f2e8eef98e1a97d8de Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Thu, 20 Feb 2025 13:56:49 +0100 Subject: [PATCH 8/8] Apply suggestions from review Co-authored-by: Petr Viktorin --- Doc/c-api/unicode.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 0eff4040bba785..e79aa94036e207 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1398,12 +1398,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) @@ -1421,6 +1429,10 @@ They all return ``NULL`` or ``-1`` if an exception occurs. *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) @@ -1430,6 +1442,10 @@ They all return ``NULL`` or ``-1`` if an exception occurs. *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)