8000 gh-46236: Add missing PyUnicode_Append() doc by rruuaanng · Pull Request #130531 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Mar 11, 2025
Merged

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

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
60c8588
Add missing PyUnicode_Append() doc
rruuaanng Feb 25, 2025
f9f0379
Merge branch 'main' into unicode-doc
rruuaanng Feb 25, 2025
3d05490
Change the copied content
rruuaanng Feb 25, 2025
8f57a62
Add '`` ``'
rruuaanng Feb 25, 2025
eb7a478
Change doc
rruuaanng Feb 26, 2025
56129b2
Add PyUnicode_AppendAndDel function doc
rruuaanng Feb 27, 2025
eb0cba1
Change doc
rruuaanng Feb 28, 2025
d8cc5d5
Add PyUnicode_AppendAndDel to refcounts
rruuaanng Feb 28, 2025
ccc56d4
Change doc
rruuaanng Mar 1, 2025
24129a0
Change doc
rruuaanng Mar 11, 2025
0191be0
Change doc
rruuaanng Mar 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions Doc/c-api/unicode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -607,6 +607,20 @@ 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.

On error, set *p_left* to ``NULL`` (*stealing* the reference) and set an exception.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand the "stealing the reference" part. It's stolen to be put where? The reference is just destroyed by Py_DECREF() (via Py_CLEAR()).

Nitpick: the assignment is not on "p_left" but "*p_left". You should write set *\*p_left*.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggested that part--I'd also be ok with "releasing the reference," but I'm worried that's less clear.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed that Py_DECREF(left) exists only in the else block, so in general, the reference count of p_left should remain unchanged. I removed the ambiguous borrowed reference to avoid any potential misunderstandings.
(I hope I haven't misunderstood the code.)

    if (unicode_modifiable(left)
        && PyUnicode_CheckExact(right)
        && PyUnicode_KIND(right) <= PyUnicode_KIND(left)
        /* Don't resize for ascii += latin1. Convert ascii to latin1 requires
           to change the structure size, but characters are stored just after
           the structure, and so it requires to move all characters which is
           not so different than duplicating the string. */
        && !(PyUnicode_IS_ASCII(left) && !PyUnicode_IS_ASCII(right)))
    {
        /* append inplace */
        if (unicode_resize(p_left, new_len) != 0)
            goto error;

        /* copy 'right' into the newly allocated area of 'left' */
        _PyUnicode_FastCopyCharacters(*p_left, left_len, right, 0, right_len);
    }
    else {
        maxchar = PyUnicode_MAX_CHAR_VALUE(left);
        maxchar2 = PyUnicode_MAX_CHAR_VALUE(right);
        maxchar = Py_MAX(maxchar, maxchar2);

        /* Concat the two Unicode strings */
        res = PyUnicode_New(new_len, maxchar);
        if (res == NULL)
            goto error;
        _PyUnicode_FastCopyCharacters(res, 0, left, 0, left_len);
        _PyUnicode_FastCopyCharacters(res, left_len, right, 0, right_len);
        Py_DECREF(left);
        *p_left = res;
    }



.. c:function:: void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)

The function is identical 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"``.
Expand Down
8 changes: 8 additions & 0 deletions Doc/data/refcounts.dat
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down
Loading
0