Repository navigation
Commit 4d3b405
authored
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.
1 parent 3229a4e commit 4d3b405
1 file changed
Lines changed: 28 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -16,6 +16,13 @@ points must be below 1114112 (which is the full Unicode range). | |||
| 16 | 16 | ||
| 17 | 17 | UTF-8 representation is created on demand and cached in the Unicode object. | |
| 18 | 18 | ||
| 19 | + .. impl-detail:: | ||
| 20 | + | ||
| 21 | + The internal buffer always includes an extra trailing null character for | ||
| 22 | + compatibility with null terminated C strings. This extra character is not | ||
| 23 | + counted in :c:func:`PyUnicode_GetLength` nor in the various *size* arguments | ||
| 24 | + of the functions below. | ||
| 25 | + | ||
| 19 | 26 | .. note:: | |
| 20 | 27 | The :c:type:`Py_UNICODE` representation has been removed since Python 3.12 | |
| 21 | 28 | with deprecated APIs. | |
@@ -164,11 +171,15 @@ access to internal read-only data of Unicode objects: | |||
| 164 | 171 | .. versionadded:: 3.3 | |
| 165 | 172 | ||
| 166 | 173 | ||
| 167 | - .. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, \ | ||
| 168 | - Py_ssize_t index) | ||
| 174 | + .. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index) | ||
| 169 | 175 | ||
| 170 | 176 | Read a code point from a canonical representation *data* (as obtained with | |
| 171 | - :c:func:`PyUnicode_DATA`). No checks or ready calls are performed. | ||
| 177 | + :c:func:`PyUnicode_DATA`). No checks are performed. | ||
| 178 | + | ||
| 179 | + .. impl-detail:: | ||
| 180 | + | ||
| 181 | + Accept reading the trailing null character at index | ||
| 182 | + :c:func:`PyUnicode_GetLength`. | ||
| 172 | 183 | ||
| 173 | 184 | .. versionadded:: 3.3 | |
| 174 | 185 | ||
@@ -179,6 +190,11 @@ access to internal read-only data of Unicode objects: | |||
| 179 | 190 | representation. This is less efficient than :c:func:`PyUnicode_READ` if you | |
| 180 | 191 | do multiple consecutive reads. | |
| 181 | 192 | ||
| 193 | + .. impl-detail:: | ||
| 194 | + | ||
| 195 | + Accept reading the trailing null character at index | ||
| 196 | + :c:func:`PyUnicode_GetLength`. | ||
| 197 | + | ||
| 182 | 198 | .. versionadded:: 3.3 | |
| 183 | 199 | ||
| 184 | 200 | ||
@@ -716,6 +732,10 @@ APIs: | |||
| 716 | 732 | ||
| 717 | 733 | On error, set an exception and return ``-1``. | |
| 718 | 734 | ||
| 735 | + .. impl-detail:: | ||
| 736 | + | ||
| 737 | + The length does not count the trailing null character. | ||
| 738 | + | ||
| 719 | 739 | .. versionadded:: 3.3 | |
| 720 | 740 | ||
| 721 | 741 | ||
@@ -794,6 +814,11 @@ APIs: | |||
| 794 | 814 | ||
| 795 | 815 | Return character on success, ``-1`` on error with an exception set. | |
| 796 | 816 | ||
| 817 | + .. impl-detail:: | ||
| 818 | + | ||
| 819 | + Do not accept reading the trailing null character at index | ||
| 820 | + :c:func:`PyUnicode_GetLength`. | ||
| 821 | + | ||
| 797 | 822 | .. versionadded:: 3.3 | |
| 798 | 823 | ||
| 799 | 824 | ||
0 commit comments