https://github.com/python/cpython/commit/823f78159d97af4767c8db391b61cadec493d4be commit: 823f78159d97af4767c8db391b61cadec493d4be branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: vstinner <[email protected]> date: 2026-10-16T13:30:18Z summary:
[3.14] gh-156939: Document that PyUnicodeObject ends with null character (GH-157708) (#159530) gh-156939: Document that PyUnicodeObject ends with null character (GH-157708) Document also that PyUnicode_READ() and PyUnicode_READ_CHAR() accept reading the trailing null character, and that PyUnicode_GetLength() doesn't count the trailing null character. (cherry picked from commit 4d3b405df82ab7b92348c242e026b4093ac211a5) Co-authored-by: Victor Stinner <[email protected]> files: M Doc/c-api/unicode.rst diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index aa2288fb77dc383..5cbe3080ff875cc 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -19,6 +19,13 @@ points must be below 1114112 (which is the full Unicode range). UTF-8 representation is created on demand and cached in the Unicode object. +.. impl-detail:: + + The internal buffer always includes an extra trailing null character for + compatibility with null terminated C strings. This extra character is not + counted in :c:func:`PyUnicode_GetLength` nor in the various *size* arguments + of the functions below. + .. note:: The :c:type:`Py_UNICODE` representation has been removed since Python 3.12 with deprecated APIs. @@ -167,11 +174,15 @@ access to internal read-only data of Unicode objects: .. versionadded:: 3.3 -.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, \ - Py_ssize_t index) +.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index) Read a code point from a canonical representation *data* (as obtained with - :c:func:`PyUnicode_DATA`). No checks or ready calls are performed. + :c:func:`PyUnicode_DATA`). No checks are performed. + + .. impl-detail:: + + Accept reading the trailing null character at index + :c:func:`PyUnicode_GetLength`. .. versionadded:: 3.3 @@ -182,6 +193,11 @@ access to internal read-only data of Unicode objects: representation. This is less efficient than :c:func:`PyUnicode_READ` if you do multiple consecutive reads. + .. impl-detail:: + + Accept reading the trailing null character at index + :c:func:`PyUnicode_GetLength`. + .. versionadded:: 3.3 @@ -703,6 +719,10 @@ APIs: On error, set an exception and return ``-1``. + .. impl-detail:: + + The length does not count the trailing null character. + .. versionadded:: 3.3 @@ -781,6 +801,11 @@ APIs: Return character on success, ``-1`` on error with an exception set. + .. impl-detail:: + + Do not accept reading the trailing null character at index + :c:func:`PyUnicode_GetLength`. + .. versionadded:: 3.3 _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
