You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<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.
[endsect]
[section Class template `iterator`]
Instances 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.
In the table below, c is an instance of Container.
[[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 [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]]
]
``
namespace boost { namespace python
{
template <class Container, class NextPolicies = unspecified>
struct iterator : object
{
iterator();
};
}}
``
[endsect]
[section Class template iterator constructors]
``iterator()``
[variablelist
[[Effects][Initializes its base class with the result of:
[[Postconditions][`this->get()` points to a Python callable object which creates a Python iterator as described above.]]
[[Rationale][Provides an easy way to create iterators for the common case where a C++ class being wrapped provides `begin()` and `end()`.]]
]
[endsect]
[section Class template `iterators`]
A 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.
[table
[[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);
};
}}
``
[endsect]
[section Class template iterators nested types]
If C is a const type,``typedef typename C::const_iterator iterator;``
[section Class template iterators static functions]
``static iterator begin(C&);``
[variablelist [[Returns][`x.begin()`]]]
``static iterator end(C&);``
[variablelist [[Returns][`x.end()`]]]
[endsect]
[section Functions]
``
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);
``
[variablelist
[[Requires][ NextPolicies is a default-constructible model of [link concepts.callpolicies CallPolicies].]]
[[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.
The second form is identical to the first, except that Target is deduced from Accessor1 as follows:
# If Accessor1 is a function type, Target is the type of its first argument.
# If Accessor1 is a data member pointer of the form `R (T::*)`, Target is identical to `T`.
# 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`.
The 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
]]
[[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.]]