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

rruuaanng · encukou · web-flow · commit faadb446d9d2 · 2025-03-11T10:28:17.000+01:00
* 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 &lt;encukou@gmail.com&gt;

* Change doc

---------

Co-authored-by: Petr Viktorin &lt;encukou@gmail.com&gt;
diff --git 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
@@ -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::
 
