From a98a9d81bbc80655356fa10117b0314799500b51 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 aa411db484e4309..b9ce05c430dff1a 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -16,6 +16,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. @@ -164,11 +171,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 @@ -179,6 +190,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 @@ -716,6 +732,10 @@ APIs: On error, set an exception and return ``-1``. + .. impl-detail:: + + The length does not count the trailing null character. + .. versionadded:: 3.3 @@ -794,6 +814,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