## boost/python/stl_iterator.hpp

### Introduction

<boost/python/stl_iterator.hpp> provides types for creating C++ Iterators from Python iterables.

### Class template `stl_input_iterator`

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.

Template Parameter | Requirements | Semantics | Default
--- | --- | --- | ---
ValueType | ValueType must be CopyConstructible. | Dereferencing an instance of `stl_input_iterator<ValueType>` will return an rvalue of type ValueType. | None

    namespace boost { namespace python
    {
      template <class ValueType>
      struct stl_input_iterator
      {
          typedef std::ptrdiff_t difference_type;
          typedef ValueType value_type;
          typedef ValueType* pointer;
          typedef ValueType reference;
          typedef std::input_iterator_tag iterator_category;

          stl_input_iterator();
          stl_input_iterator(object const& ob);

          stl_input_iterator& operator++();
          stl_input_iterator operator++(int);

          ValueType operator*() const;

          friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs);
          friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs);
      private:
          object it; // For exposition only
          object ob; // For exposition only
      };
    }}

### Class template `stl_input_iterator` constructors

    stl_input_iterator()

Effects

  Creates a past-the-end input iterator, useful for signifying the end of a sequence.

Postconditions

  `this` is past-the-end

Throws

  Nothing.

    stl_input_iterator(object const& ob)

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().

Postconditions

  this is a dereferenceable or past-the-end.

### Class template `stl_input_iterator` modifiers

    stl_input_iterator &operator++()

Effects

  Calls this->it.attr("next")() and stores the result in this->ob. If the sequence is exhausted, sets this->ob to object().

Postconditions

  this is a dereferenceable or past-the-end.

Returns

  `*this`

    stl_input_iterator &operator++(int)

Effects

  `stl_input_iterator tmp = *this; ++*this; return tmp;`

Postconditions

  this is a dereferenceable or past-the-end.

### Class template `stl_input_iterator` observers

    ValueType operator*() const

Effects

  Returns the current element in the sequence.

Returns

  `extract<ValueType>(this->ob);`

    friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs)

Effects

  Returns true if both iterators are dereferenceable or if both iterators are past-the-end, false otherwise.

Returns

  `(lhs.ob == object()) == (rhs.ob == object())`

    friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs)

Effects

  Returns false if both iterators are dereferenceable or if both iterators are past-the-end, true otherwise.

Returns

  `!(lhs == rhs)`

### Example

    #include <boost/python/object.hpp>
    #include <boost/python/stl_iterator.hpp>

    #include <list>

    using namespace boost::python;
    std::list<int> sequence_to_int_list(object const& ob)
    {
        stl_input_iterator<int> begin(ob), end;
        return std::list<int>(begin, end);
    }