← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/c-api/iter.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/iter.rst
 
1
.. highlightlang:: c
 
2
 
 
3
.. _iterator:
 
4
 
 
5
Iterator Protocol
 
6
=================
 
7
 
 
8
There are only a couple of functions specifically for working with iterators.
 
9
 
 
10
.. cfunction:: int PyIter_Check(PyObject *o)
 
11
 
 
12
   Return true if the object *o* supports the iterator protocol.
 
13
 
 
14
 
 
15
.. cfunction:: PyObject* PyIter_Next(PyObject *o)
 
16
 
 
17
   Return the next value from the iteration *o*.  If the object is an iterator,
 
18
   this retrieves the next value from the iteration, and returns *NULL* with no
 
19
   exception set if there are no remaining items.  If the object is not an
 
20
   iterator, :exc:`TypeError` is raised, or if there is an error in retrieving the
 
21
   item, returns *NULL* and passes along the exception.
 
22
 
 
23
To write a loop which iterates over an iterator, the C code should look
 
24
something like this::
 
25
 
 
26
   PyObject *iterator = PyObject_GetIter(obj);
 
27
   PyObject *item;
 
28
 
 
29
   if (iterator == NULL) {
 
30
       /* propagate error */
 
31
   }
 
32
 
 
33
   while (item = PyIter_Next(iterator)) {
 
34
       /* do something with item */
 
35
       ...
 
36
       /* release reference when done */
 
37
       Py_DECREF(item);
 
38
   }
 
39
 
 
40
   Py_DECREF(iterator);
 
41
 
 
42
   if (PyErr_Occurred()) {
 
43
       /* propagate error */
 
44
   }
 
45
   else {
 
46
       /* continue doing useful work */
 
47
   }