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

   1 [section boost/python/stl_iterator.hpp]
   2 [section Introduction]
   3 <boost/python/stl_iterator.hpp> provides types for creating C++ Iterators from [@http://www.python.org/doc/current/lib/typeiter.html Python iterables].
   4 [endsect]
   5 [section Class template `stl_input_iterator`]
   6 Instances of `stl_input_iterator<T>` hold a Python iterator and adapt it for use with STL algorithms. `stl_input_iterator<T>` satisfies the requirements for an Input Iterator.
   7 [table
   8 [[Template Parameter][Requirements][Semantics][Default]]
   9 [[ValueType][ValueType must be CopyConstructible.][Dereferencing an instance of `stl_input_iterator<ValueType>` will return an rvalue of type ValueType.][None]]
  10 ]
  11 ``
  12 namespace boost { namespace python
  13 {
  14   template <class ValueType>
  15   struct stl_input_iterator
  16   {
  17       typedef std::ptrdiff_t difference_type;
  18       typedef ValueType value_type;
  19       typedef ValueType* pointer;
  20       typedef ValueType reference;
  21       typedef std::input_iterator_tag iterator_category;
  22
  23       stl_input_iterator();
  24       stl_input_iterator(object const& ob);
  25
  26       stl_input_iterator& operator++();
  27       stl_input_iterator operator++(int);
  28
  29       ValueType operator*() const;
  30
  31       friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs);
  32       friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs);
  33   private:
  34       object it; // For exposition only
  35       object ob; // For exposition only
  36   };
  37 }}
  38 ``
  39 [endsect]
  40 [section Class template `stl_input_iterator` constructors]
  41 ``
  42 stl_input_iterator()
  43 ``
  44 [variablelist
  45 [[Effects][Creates a past-the-end input iterator, useful for signifying the end of a sequence. ]]
  46 [[Postconditions][`this` is past-the-end]]
  47 [[Throws][Nothing.]]
  48 ]
  49 ``stl_input_iterator(object const& ob)``
  50 [variablelist
  51 [[Effects][Calls ob.attr("__iter__")() and stores the resulting Python iterator object in this->it. Then, calls this->it.attr("next")() and stores the result in this->ob. If the sequence is exhausted, sets this->ob to object(). ]]
  52 [[Postconditions][this is a dereferenceable or past-the-end.]]
  53 ]
  54 [endsect]
  55 [section Class template `stl_input_iterator` modifiers]
  56 ``
  57 stl_input_iterator &operator++()
  58 ``
  59 [variablelist
  60 [[Effects][Calls this->it.attr("next")() and stores the result in this->ob. If the sequence is exhausted, sets this->ob to object(). ]]
  61 [[Postconditions][this is a dereferenceable or past-the-end.]]
  62 [[Returns][`*this`]]
  63 ]
  64 ``stl_input_iterator &operator++(int)``
  65 [variablelist
  66 [[Effects][`stl_input_iterator tmp = *this; ++*this; return tmp;`]]
  67 [[Postconditions][this is a dereferenceable or past-the-end.]]
  68 ]
  69 [endsect]
  70 [section Class template `stl_input_iterator` observers]
  71 ``
  72 ValueType operator*() const
  73 ``
  74 [variablelist
  75 [[Effects][Returns the current element in the sequence. ]]
  76 [[Returns][`extract<ValueType>(this->ob);`]]
  77 ]
  78 ``
  79 friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs)
  80 ``
  81 [variablelist
  82 [[Effects][Returns true if both iterators are dereferenceable or if both iterators are past-the-end, false otherwise. ]]
  83 [[Returns][`(lhs.ob == object()) == (rhs.ob == object())`]]
  84 ]
  85 ``
  86 friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs)
  87 ``
  88 [variablelist
  89 [[Effects][Returns false if both iterators are dereferenceable or if both iterators are past-the-end, true otherwise. ]]
  90 [[Returns][`!(lhs == rhs)`]]
  91 ]
  92 [endsect]
  93 [section Example]
  94 ``
  95 #include <boost/python/object.hpp>
  96 #include <boost/python/stl_iterator.hpp>
  97
  98 #include <list>
  99
 100 using namespace boost::python;
 101 std::list<int> sequence_to_int_list(object const& ob)
 102 {
 103     stl_input_iterator<int> begin(ob), end;
 104     return std::list<int>(begin, end);
 105 }
 106 ``
 107 [endsect]
 108 [endsect]