From 34ac4bf2ca49adee0579f49ebaf54beca0a121ee Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Sat, 19 Sep 2026 15:56:08 +0200 Subject: [PATCH] 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 --- Doc/c-api/unicode.rst | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index aa2288fb77dc38..5cbe3080ff875c 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