| 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-2003 David Abrahams
Copyright © 2002-2003 Joel de Guzman
Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.