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.

Author: vstinner

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