gh-46236: Add PyUnicode_Resize() doc (#132628)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 778ee9890c5a82044d86d87df85836b803b6ddeb..6a20b0cd8ddae6401fb4c5b1e0f6466b6355dcd6 100644 (file)
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -674,6 +674,21 @@ APIs:
    .. versionadded:: 3.3
 
 
+.. c:function:: int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);
+
+   Resize a Unicode object *\*unicode* to the new *length* in code points.
+
+   Try to resize the string in place (which is usually faster than allocating
+   a new string and copying characters), or create a new string.
+
+   *\*unicode* is modified to point to the new (resized) object and ``0`` is
+   returned on success. Otherwise, ``-1`` is returned and an exception is set,
+   and *\*unicode* is left untouched.
+
+   The function doesn't check string content, the result may not be a
+   string in canonical representation.
+
+
 .. c:function:: Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, \
                         Py_ssize_t length, Py_UCS4 fill_char)
 

diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 47b417eed6efda90f57f969257b1bf3bd8b1efe5..ca99b9e6d371418e20d5a67a6cd68414e2721a2b 100644 (file)
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -2794,6 +2794,10 @@ PyUnicode_CopyCharacters:PyObject*:from:0:
 PyUnicode_CopyCharacters:Py_ssize_t:from_start::
 PyUnicode_CopyCharacters:Py_ssize_t:how_many::
 
+PyUnicode_Resize:int:::
+PyUnicode_Resize:PyObject**:unicode:0:
+PyUnicode_Resize:Py_ssize_t:length::
+
 PyUnicode_Fill:Py_ssize_t:::
 PyUnicode_Fill:PyObject*:unicode:0:
 PyUnicode_Fill:Py_ssize_t:start::