https://github.com/python/cpython/commit/4d3b405df82ab7b92348c242e026b4093ac211a5
commit: 4d3b405df82ab7b92348c242e026b4093ac211a5
branch: main
author: Victor Stinner <[email protected]>
committer: vstinner <[email protected]>
date: 2026-09-19T13:56:08Z
summary:
gh-156939: Document that PyUnicodeObject ends with null character (#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.
files:
M Doc/c-api/unicode.rst
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 8ac4e137709555..3b635fa7fa3744 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
_______________________________________________
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]
