From dbcaeda79a7ba2c4b41462b32f1e60201b523eea Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Mon, 7 May 2001 17:42:18 +0000
Subject: Added documentation for PyIter_Check() and PyIter_Next().

Wrapped a long line.
---
 Doc/api/api.tex | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 0d7f6f2..b441c4a 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -2082,13 +2082,51 @@ Return element of \var{o} corresponding to the object \var{key} or
 \samp{\var{o}[\var{key}]}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
+\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}
+
+
 \chapter{Concrete Objects Layer \label{concrete}}
 
 The functions in this chapter are specific to certain Python object
-- 
cgit v0.12