From: Fred Drake <fdrake@acm.org>
Date: Sun, 3 Jun 2001 03:12:57 +0000 (+0000)
Subject: Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
X-Git-Tag: v2.2a3~1627
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=00d0cb6ec3198234f27e98fca9ee6e152dd8abeb;p=python

Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
In particular, the affect on existing list content was not sufficiently
explained.

This closes SF bug #429554.
---

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 613f62cb73..a4886a7ec4 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -3304,13 +3304,18 @@ Macro form of \cfunction{PyList_GetItem()} without error checking.
 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
                                        PyObject *item}
 Sets the item at index \var{index} in list to \var{item}.
-\strong{Note:}  This function ``steals'' a reference to \var{item}.
+\strong{Note:}  This function ``steals'' a reference to \var{item} and
+discards a reference to an item already in the list at the affected
+position.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyList_SET_ITEM}{PyObject *list, int i,
                                               PyObject *o}
 Macro form of \cfunction{PyList_SetItem()} without error checking.
-\strong{Note:}  This function ``steals'' a reference to \var{item}.
+\strong{Note:}  This function ``steals'' a reference to \var{item},
+and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
+reference to any item that it being replaced.  This is normally only
+used to fill in new lists where there is no previous content..
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,