[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.118,1.119

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv31750/api

Modified Files:
	api.tex 
Log Message:

Added documentation for PyIter_Check() and PyIter_Next().

Wrapped a long line.


Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.118
retrieving revision 1.119
diff -C2 -r1.118 -r1.119
*** api.tex	2001/04/23 14:44:21	1.118
--- api.tex	2001/05/07 17:42:18	1.119
***************
*** 2083,2091 ****
  \end{cfuncdesc}
  
! \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
  Map the object \var{key} to the value \var{v} in object \var{o}.
  Returns \code{-1} on failure.  This is the equivalent of the Python
  statement \samp{\var{o}[\var{key}] = \var{v}}.
  \end{cfuncdesc}
  
  
--- 2083,2129 ----
  \end{cfuncdesc}
  
! \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key,
!                                                 PyObject *v}
  Map the object \var{key} to the value \var{v} in object \var{o}.
  Returns \code{-1} on failure.  This is the equivalent of the Python
  statement \samp{\var{o}[\var{key}] = \var{v}}.
  \end{cfuncdesc}
+ 
+ 
+ \section{Iterator Protocol \label{iterator}}
+ 
+ There are only a couple of functions specifically for working with
+ iterators.
+ 
+ \begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
+   Return true if the object \var{o} supports the iterator protocol.
+ \end{cfuncdesc}
+ 
+ \begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o}
+   Return the next value from the iteration \var{o}.  If the object is
+   an iterator, this retrieves the next value from the iteration, and
+   returns \NULL{} with no exception set if there are no remaining
+   items.  If the object is not an iterator, \exception{TypeError} is
+   raised, or if there is an error in retrieving the item, returns
+   \NULL{} and passes along the exception.
+ \end{cfuncdesc}
+ 
+ To write a loop which iterates over an iterator, the C code should
+ look something like this:
+ 
+ \begin{verbatim}
+ PyObject *iterator = ...;
+ PyObject *item;
+ 
+ while (item = PyIter_Next(iter)) {
+     /* do something with item */
+ }
+ if (PyErr_Occurred()) {
+     /* propogate error */
+ }
+ else {
+     /* continue doing useful work */
+ }
+ \end{verbatim}