1[section boost/python/iterator.hpp] 2[section Introduction] 3<boost/python/iterator.hpp> provides types and functions for creating [@http://www.python.org/doc/current/lib/typeiter.html Python iterators] from C++ Containers and Iterators. Note that if your `class_` supports random-access iterators, implementing [@http://www.python.org/doc/current/ref/sequence-types.html#l2h-128 __getitem__] (also known as the Sequence Protocol) may serve you better than using this facility: Python will automatically create an iterator type for you (see [@http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35 `iter()`]), and each access can be range-checked, leaving no possiblity of accessing through an invalidated C++ iterator. 4[endsect] 5[section Class template `iterator`] 6Instances of `iterator<C,P>` hold a reference to a callable Python object which, when invoked from Python, expects a single argument c convertible to C and creates a Python iterator that traverses `[c.begin(), c.end())`. The optional [link concepts.callpolicies CallPolicies] `P` can be used to control how elements are returned during iteration. 7 8In the table below, c is an instance of Container. 9 10[table 11[[Template Parameter][Requirements][Semantics][Default]] 12[[Container][`[c.begin(),c.end()`) is a valid Iterator range.][The result will convert its argument to c and call c.begin() and c.end() to acquire iterators. To invoke Container's const `begin()` and `end()` functions, make it const.][ ]] 13[[NextPolicies][A default-constructible model of [link concepts.callpolicies CallPolicies].][Applied to the resulting iterators' `next()` method.][An unspecified model of [link concepts.callpolicies CallPolicies] which always makes a copy of the result of deferencing the underlying C++ iterator]] 14] 15 16`` 17namespace boost { namespace python 18 { 19 template <class Container, class NextPolicies = unspecified> 20 struct iterator : object 21 { 22 iterator(); 23 }; 24 }} 25`` 26[endsect] 27[section Class template iterator constructors] 28``iterator()`` 29 30[variablelist 31[[Effects][Initializes its base class with the result of: 32``range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end)``]] 33[[Postconditions][`this->get()` points to a Python callable object which creates a Python iterator as described above.]] 34[[Rationale][Provides an easy way to create iterators for the common case where a C++ class being wrapped provides `begin()` and `end()`.]] 35] 36[endsect] 37[section Class template `iterators`] 38A utility class template which provides a way to reliably call its argument's `begin()` and `end()` member functions. Note that there is no portable way to take the address of a member function of a C++ standard library container, so `iterators<>` can be particularly helpful when wrapping them. 39 40In the table below, x is an instance of C. 41[table 42[[Required Valid Expression][Type]] 43[[x.begin()][Convertible to C::const_iterator if C is a const type; convertible to C::iterator otherwise.]] 44[[x.end()][Convertible to C::const_iterator if C is a const type; convertible to C::iterator otherwise.]] 45] 46`` 47namespace boost { namespace python 48{ 49 template <class C> 50 struct iterators 51 { 52 typedef typename C::const_iterator iterator; 53 static iterator begin(C& x); 54 static iterator end(C& x); 55 }; 56}} 57`` 58[endsect] 59[section Class template iterators nested types] 60If C is a const type,``typedef typename C::const_iterator iterator;`` 61Otherwise: ``typedef typename C::iterator iterator;`` 62[endsect] 63[section Class template iterators static functions] 64``static iterator begin(C&);`` 65[variablelist [[Returns][`x.begin()`]]] 66``static iterator end(C&);`` 67[variablelist [[Returns][`x.end()`]]] 68[endsect] 69[section Functions] 70`` 71template <class NextPolicies, class Target, class Accessor1, class Accessor2> 72object range(Accessor1 start, Accessor2 finish); 73 74template <class NextPolicies, class Accessor1, class Accessor2> 75object range(Accessor1 start, Accessor2 finish); 76 77template <class Accessor1, class Accessor2> 78object range(Accessor1 start, Accessor2 finish); 79`` 80[variablelist 81[[Requires][ NextPolicies is a default-constructible model of [link concepts.callpolicies CallPolicies].]] 82[[Effects][The first form creates a Python callable object which, when invoked, converts its argument to a Target object x, and creates a Python iterator which traverses `[bind(start,_1)(x), bind(finish,_1)(x))`, applying NextPolicies to the iterator's `next()` function. 83The second form is identical to the first, except that Target is deduced from Accessor1 as follows: 84 85# If Accessor1 is a function type, Target is the type of its first argument. 86# If Accessor1 is a data member pointer of the form `R (T::*)`, Target is identical to `T`. 87# If Accessor1 is a member function pointer of the form `R (T::*)(arguments...) cv-opt`, where cv-opt is an optional cv-qualifier, Target is identical to `T`. 88 89The third form is identical to the second, except that NextPolicies is an unspecified model of [link concepts.callpolicies CallPolicies] which always makes a copy of the result of deferencing the underlying C++ iterator 90 91]] 92[[Rationale][The use of `boost::bind()` allows C++ iterators to be accessed through functions, member functions or data member pointers. Customization of NextPolicies (e.g. using [link function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r return_internal_reference]) is useful when it is expensive to copy sequence elements of a wrapped class type. Customization of Target is useful when Accessor1 is a function object, or when a base class of the intended target type would otherwise be deduced.]] 93] 94[endsect] 95[section Example] 96`` 97#include <boost/python/module.hpp> 98#include <boost/python/class.hpp> 99 100#include <vector> 101 102using namespace boost::python; 103BOOST_PYTHON_MODULE(demo) 104{ 105 class_<std::vector<double> >("dvec") 106 .def("__iter__", iterator<std::vector<double> >()) 107 ; 108} 109`` 110[endsect] 111[endsect] 112