Iterators

| Home | Libraries | People | FAQ | More

## Iterators

In C++, and STL in particular, we see iterators everywhere. Python also has iterators, but these are two very different beasts.

C++ iterators:

- C++ has 5 type categories (random-access, bidirectional, forward, input, output)
- There are 2 Operation categories: reposition, access
- A pair of iterators is needed to represent a (first/last) range.

Python Iterators:

- 1 category (forward)
- 1 operation category (next())
- Raises StopIteration exception at end

The typical Python iteration protocol: `for y in x...` is as follows:

    iter = x.__iter__()         # get iterator
    try:
        while 1:
        y = iter.next()         # get each item
        ...                     # process y
    except StopIteration: pass  # iterator exhausted

Boost.Python provides some mechanisms to make C++ iterators play along nicely as Python iterators. What we need to do is to produce appropriate _iter_ function from C++ iterators that is compatible with the Python iteration protocol. For example:

    object get_iterator = iterator<vector<int> >();
    object iter = get_iterator(v);
    object first = iter.next();

Or for use in class_<>:

    .def("__iter__", iterator<vector<int> >())

range

We can create a Python savvy iterator using the range function:

- range(start, finish)
- range<Policies,Target>(start, finish)

Here, start/finish may be one of:

- member data pointers
- member function pointers
- adaptable function object (use Target parameter)

iterator

- iterator<T, Policies>()

Given a container `T`, iterator is a shortcut that simply calls `range` with &T::begin, &T::end.

Let's put this into action... Here's an example from some hypothetical bogon Particle accelerator code:

    f = Field()
    for x in f.pions:
        smash(x)
    for y in f.bogons:
        count(y)

Now, our C++ Wrapper:

    class_<F>("Field")
        .property("pions", range(&F::p_begin, &F::p_end))
        .property("bogons", range(&F::b_begin, &F::b_end));

| Copyright © 2002-2004 Joel de Guzman, David Abrahams