Add _PyBytes_Resize() example

Author: vstinner

peps/pep-0782.rst

@@ -283,8 +283,8 @@ Example creating the bytes string ``b"abc"``, with a fixed size of 3 bytes::
         return PyBytesWriter_Finish(writer);
     }
 
-GrowAndUpdatePointer() example
-------------------------------
+``GrowAndUpdatePointer()`` example
+----------------------------------
 
 Example using a pointer to write bytes and to track the written size.
 
@@ -326,26 +326,57 @@ Update ``PyBytes_FromStringAndSize()`` code
 Example of code using the soft deprecated
 ``PyBytes_FromStringAndSize(NULL, size)`` API::
 
-        PyObject *result = PyBytes_FromStringAndSize(NULL, num_bytes);
-        if (result == NULL) {
-            return NULL;
-        }
-        if (safe_memcpy(PyBytes_AS_STRING(result), start, num_bytes) < 0) {
-            Py_CLEAR(result);
-        }
-        return result;
+    PyObject *result = PyBytes_FromStringAndSize(NULL, num_bytes);
+    if (result == NULL) {
+        return NULL;
+    }
+    if (safe_memcpy(PyBytes_AS_STRING(result), start, num_bytes) < 0) {
+        Py_CLEAR(result);
+    }
+    return result;
 
 It can now be updated to::
 
-        PyBytesWriter *writer = PyBytesWriter_Create(num_bytes);
-        if (writer == NULL) {
-            return NULL;
-        }
-        if (safe_memcpy(PyBytesWriter_GetData(writer), start, num_bytes) < 0) {
-            PyBytesWriter_Discard(writer);
-            return NULL;
-        }
-        return PyBytesWriter_Finish(writer);
+    PyBytesWriter *writer = PyBytesWriter_Create(num_bytes);
+    if (writer == NULL) {
+        return NULL;
+    }
+    if (safe_memcpy(PyBytesWriter_GetData(writer), start, num_bytes) < 0) {
+        PyBytesWriter_Discard(writer);
+        return NULL;
+    }
+    return PyBytesWriter_Finish(writer);
+
+
+Update ``_PyBytes_Resize()`` code
+---------------------------------
+
+Example of code using the soft deprecated ``_PyBytes_Resize()`` API::
+
+    PyObject *v = PyBytes_FromStringAndSize(NULL, size);
+    if (v == NULL) {
+        return NULL;
+    }
+    char *p = PyBytes_AS_STRING(v);
+
+    // ... fill bytes into 'p' ...
+
+    if (_PyBytes_Resize(&v, (p - PyBytes_AS_STRING(v)))) {
+        return NULL;
+    }
+    return v;
+
+It can now be updated to::
+
+    PyBytesWriter *writer = PyBytesWriter_Create(size);
+    if (writer == NULL) {
+        return NULL;
+    }
+    char *p = PyBytesWriter_GetData(writer);
+
+    // ... fill bytes into 'p' ...
+
+    return PyBytesWriter_FinishWithPointer(writer, p);
 
 
 Reference Implementation