gh-46236: Add missing PyUnicode_Append() doc

[rruuaanng]

• Issue: Document PyUnicode_* API #46236

---

📚 Documentation preview 📚: https://cpython-previews--130531.org.readthedocs.build/

[rruuaanng]

cc @encukou

[encukou]

The docs should explain the unusual reference counting behaviour -- the function is “reference-neutral”, as in PyUnicode_InternInPlace, but on error you lose the reference *p_left.

Would you mind documenting PyUnicode_AppendAndDel as well?

[rruuaanng]

The docs should explain the unusual reference counting behaviour -- the function is “reference-neutral”, as in PyUnicode_InternInPlace, but on error you lose the reference *p_left.

Would you mind documenting PyUnicode_AppendAndDel as well?

Of course, I accept any reasonable request.

Edit

Oh, by the way, could you help me check off the tasks in the issue checklist? It seems they haven’t been updated in a while.

[encukou]

Oh, by the way, could you help me check off the tasks in the issue checklist? It seems they haven’t been updated in a while.

I'm checking them off when the docs are merged, but if there's one I missed let me know which one.

[vstinner]

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*.

[ZeroIntensity]

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

[rruuaanng]

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;
    }

[vstinner]

LGTM