Repair widespread misuse of _PyString_Resize. Since it's clear people
don't understand how this function works, also beefed up the docs. The
most common usage error is of this form (often spread out across gotos):
if (_PyString_Resize(&s, n) < 0) {
Py_DECREF(s);
s = NULL;
goto outtahere;
}
The error is that if _PyString_Resize runs out of memory, it automatically
decrefs the input string object s (which also deallocates it, since its
refcount must be 1 upon entry), and sets s to NULL. So if the "if"
branch ever triggers, it's an error to call Py_DECREF(s): s is already
NULL! A correct way to write the above is the simpler (and intended)
if (_PyString_Resize(&s, n) < 0)
goto outtahere;
Bugfix candidate.
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index 9762924..26a82d3 100644
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -586,7 +586,16 @@
\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
A way to resize a string object even though it is ``immutable''.
Only use this to build up a brand new string object; don't use this
- if the string may already be known in other parts of the code.
+ if the string may already be known in other parts of the code. It
+ is an error to call this function if the refcount on the input string
+ object is not one.
+ Pass the address of an existing string object as an lvalue (it may
+ be written into), and the new size desired. On success, \var{*string}
+ holds the resized string object and 0 is returned; the address in
+ \var{*string} may differ from its input value. If the
+ reallocation fails, the original string object at \var{*string} is
+ deallocated, \var{*string} is set to \NULL{}, a memory exception is set,
+ and -1 is returned.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,