ceph/src/boost/libs/python/doc/reference/iterator.qbk

   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`]
   6 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.
   7
   8 In 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 ``
  17 namespace 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`]
  38 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.
  39
  40 In 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 ``
  47 namespace 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]
  60 If C is a const type,``typedef typename C::const_iterator iterator;``
  61 Otherwise: ``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 ``
  71 template <class NextPolicies, class Target, class Accessor1, class Accessor2>
  72 object range(Accessor1 start, Accessor2 finish);
  73
  74 template <class NextPolicies, class Accessor1, class Accessor2>
  75 object range(Accessor1 start, Accessor2 finish);
  76
  77 template <class Accessor1, class Accessor2>
  78 object 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.
  83 The 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
  89 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
  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
 102 using namespace boost::python;
 103 BOOST_PYTHON_MODULE(demo)
 104 {
 105     class_<std::vector<double> >("dvec")
 106         .def("__iter__", iterator<std::vector<double> >())
 107         ;
 108 }
 109 ``
 110 [endsect]
 111 [endsect]