###

# Boost.Python

## Header <boost/python/stl_iterator.hpp>

## Contents

Introduction
Classes
  Class template `stl_input_iterator`
    Class `stl_input_iterator` synopsis
    Class template `stl_input_iterator` constructors
    Class template `stl_input_iterator` modifiers
    Class template `stl_input_iterator` observers
Examples

## Introduction

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

## Classes

### 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

#### Class Template stl_input_iterator synopsis

    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)`

## Examples

    #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);
    }

Revised 30 October, 2005

© Copyright Eric Niebler 2005.