From: RUANG (James Roy) <rruuaanng@outlook.com>
Date: Tue, 11 Mar 2025 09:28:17 +0000 (+0800)
Subject: gh-46236: Add missing PyUnicode_Append() doc (#130531)
X-Git-Tag: v3.14.0a6~88
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=faadb446d9d26827e23dc1cf68ffb6218bc70d32;p=thirdparty%2FPython%2Fcpython.git

gh-46236: Add missing PyUnicode_Append() doc (#130531)

* Add missing PyUnicode_Append() doc

* Change the copied content

* Add '`` ``'

* Change doc

* Add PyUnicode_AppendAndDel function doc

* Change doc

* Add PyUnicode_AppendAndDel to refcounts

* Change doc

* Change doc

Co-authored-by: Petr Viktorin <encukou@gmail.com>

* Change doc

---------

Co-authored-by: Petr Viktorin <encukou@gmail.com>
---

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index d359a6debf5e..65b5aa76afe3 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -614,6 +614,23 @@ APIs:
    decref'ing the returned objects.
 
 
+.. c:function:: void PyUnicode_Append(PyObject **p_left, PyObject *right)
+
+   Append the string *right* to the end of *p_left*.
+   *p_left* must point to a :term:`strong reference` to a Unicode object;
+   :c:func:`!PyUnicode_Append` releases ("steals") this reference.
+
+   On error, set *\*p_left* to ``NULL`` and set an exception.
+
+   On sucess, set *\*p_left* to a new strong reference to the result.
+
+
+.. c:function:: void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)
+
+   The function is similar to :c:func:`PyUnicode_Append`, with the only
+   difference being that it decrements the reference count of *right* by one.
+
+
 .. c:function:: const char* PyUnicode_GetDefaultEncoding(void)
 
    Return the name of the default string encoding, ``"utf-8"``.
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 15591fbefcd5..14629fbff0fb 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -2770,6 +2770,14 @@ PyUnicode_FromFormatV:PyObject*::+1:
 PyUnicode_FromFormatV:const char*:format::
 PyUnicode_FromFormatV:va_list:args::
 
+PyUnicode_Append:void:::
+PyUnicode_Append:PyObject**:p_left:0:
+PyUnicode_Append:PyObject*:right::
+
+PyUnicode_AppendAndDel:void:::
+PyUnicode_AppendAndDel:PyObject**:p_left:0:
+PyUnicode_AppendAndDel:PyObject*:right:-1:
+
 PyUnicode_GetDefaultEncoding:const char*:::
 PyUnicode_GetDefaultEncoding::void::