|
|
Boost.PythonHeader <boost/python/iterator.hpp> |
iteratoriterator synopsisiterator constructoriteratorsiterators synopsisiterators nested typesiterators static functions<boost/python/iterator.hpp> provides types and
functions for creating Python
iterators from C++ Containers and Iterators. Note
that if your class_ supports random-access iterators,
implementing __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 iter()),
and each access can be range-checked, leaving no possiblity of accessing
through an invalidated C++ iterator.
iteratorInstances 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 CallPolicies P can be used to
control how elements are returned during iteration.
In the table below, c is an instance of
Container.
| Template Parameter | Requirements | Semantics | Default |
|---|---|---|---|
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. |
|
NextPolicies |
A default-constructible model of CallPolicies. | Applied to the resulting iterators' next()
method. |
An unspecified model of CallPolicies which always makes a copy of the result of deferencing the underlying C++ iterator |
namespace boost { namespace python
{
template <class Container
, class NextPolicies = unspecified>
struct iterator : object
{
iterator();
};
}}
iterator()
range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end)
this->get() points to a
Python callable object which creates a Python iterator as described
above.begin() and end().iteratorsA 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.
In the table below, x is an instance of
C.
| Required Valid Expression | Type |
|---|---|
x.begin() |
Convertible to C::const_iterator if C
is a const type; convertible to C::iterator
otherwise. |
x.end() |
Convertible to C::const_iterator if C
is a const type; convertible to C::iterator
otherwise. |
namespace boost { namespace python
{
template <class C>
struct iterators
{
typedef typename C::[const_]iterator iterator;
static iterator begin(C& x);
static iterator end(C& x);
};
}}
const type,
typedef typename C::const_iterator iterator;Otherwise:
typedef typename C::iterator iterator;
static iterator begin(C&);
x.begin()static iterator end(C&);
x.end()template <class NextPolicies, class Target, class Accessor1, class Accessor2> object range(Accessor1 start, Accessor2 finish); template <class NextPolicies, class Accessor1, class Accessor2> object range(Accessor1 start, Accessor2 finish); template <class Accessor1, class Accessor2> object range(Accessor1 start, Accessor2 finish);
NextPolicies is a
default-constructible model of CallPolicies.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.Target is deduced from Accessor1 as
follows:Accessor1 is a function type,
Target is the type of its first argument.Accessor1 is a data member pointer of the
form R (T::*), Target is
identical to T.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.NextPolicies is an unspecified model of CallPolicies which
always makes a copy of the result of deferencing the underlying C++
iteratorboost::bind() allows C++ iterators
to be accessed through functions, member functions or data member
pointers. Customization of NextPolicies (e.g. using
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.
#include <boost/python/module.hpp>
#include <boost/python/class.hpp>
#include <vector>
using namespace boost::python;
BOOST_PYTHON_MODULE(demo)
{
class_<std::vector<double> >("dvec")
.def("__iter__", iterator<std::vector<double> >())
;
}
A more comprehensive example can be found in:
libs/python/test/iterator.cpplibs/python/test/input_iterator.cpplibs/python/test/input_iterator.pyRevised 13 November, 2002
© Copyright Dave Abrahams 2002.