#23088: Clarify null termination of bytes and strings in C API.

Patch by Martin Panter, reviewed by Serhiy Storchaka and R. David Murray.

1 files changed, 18 insertions, 14 deletions

diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index 5666dac..23b7128 100644
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -69,8 +69,8 @@ called with a non-bytes parameter.
    +===================+===============+================================+
    | :attr:`%%`        | *n/a*         | The literal % character.       |
    +-------------------+---------------+--------------------------------+
-   | :attr:`%c`        | int           | A single character,            |
-   |                   |               | represented as an C int.       |
+   | :attr:`%c`        | int           | A single byte,                 |
+   |                   |               | represented as a C int.        |
    +-------------------+---------------+--------------------------------+
    | :attr:`%d`        | int           | Exactly equivalent to          |
    |                   |               | ``printf("%d")``.              |
@@ -109,7 +109,7 @@ called with a non-bytes parameter.
    +-------------------+---------------+--------------------------------+
 
    An unrecognized format character causes all the rest of the format string to be
-   copied as-is to the result string, and any extra arguments discarded.
+   copied as-is to the result object, and any extra arguments discarded.
 
 
 .. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
@@ -136,11 +136,13 @@ called with a non-bytes parameter.
 
 .. c:function:: char* PyBytes_AsString(PyObject *o)
 
-   Return a NUL-terminated representation of the contents of *o*.  The pointer
-   refers to the internal buffer of *o*, not a copy.  The data must not be
-   modified in any way, unless the string was just created using
+   Return a pointer to the contents of *o*.  The pointer
+   refers to the internal buffer of *o*, which consists of ``len(o) + 1``
+   bytes.  The last byte in the buffer is always null, regardless of
+   whether there are any other null bytes.  The data must not be
+   modified in any way, unless the object was just created using
    ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
-   *o* is not a string object at all, :c:func:`PyBytes_AsString` returns *NULL*
+   *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL*
    and raises :exc:`TypeError`.
 
 
@@ -151,16 +153,18 @@ called with a non-bytes parameter.
 
 .. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
 
-   Return a NUL-terminated representation of the contents of the object *obj*
+   Return the null-terminated contents of the object *obj*
    through the output variables *buffer* and *length*.
 
-   If *length* is *NULL*, the resulting buffer may not contain NUL characters;
+   If *length* is *NULL*, the bytes object
+   may not contain embedded null bytes;
    if it does, the function returns ``-1`` and a :exc:`TypeError` is raised.
 
-   The buffer refers to an internal string buffer of *obj*, not a copy. The data
-   must not be modified in any way, unless the string was just created using
+   The buffer refers to an internal buffer of *obj*, which includes an
+   additional null byte at the end (not counted in *length*).  The data
+   must not be modified in any way, unless the object was just created using
    ``PyBytes_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
-   *string* is not a string object at all, :c:func:`PyBytes_AsStringAndSize`
+   *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize`
    returns ``-1`` and raises :exc:`TypeError`.
 
 
@@ -168,14 +172,14 @@ called with a non-bytes parameter.
 
    Create a new bytes object in *\*bytes* containing the contents of *newpart*
    appended to *bytes*; the caller will own the new reference.  The reference to
-   the old value of *bytes* will be stolen.  If the new string cannot be
+   the old value of *bytes* will be stolen.  If the new object cannot be
    created, the old reference to *bytes* will still be discarded and the value
    of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
 
 
 .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
 
-   Create a new string object in *\*bytes* containing the contents of *newpart*
+   Create a new bytes object in *\*bytes* containing the contents of *newpart*
    appended to *bytes*.  This version decrements the reference count of
    *newpart*.