| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| |
| <!-- Copyright David Abrahams 2006. Distributed under the Boost --> |
| <!-- Software License, Version 1.0. (See accompanying --> |
| <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> |
| <html> |
| <head> |
| <meta name="generator" content= |
| "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link rel="stylesheet" type="text/css" href="../boost.css"> |
| |
| <title>Boost.Python - <boost/python/iterator.hpp></title> |
| </head> |
| |
| <body> |
| <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
| "header"> |
| <tr> |
| <td valign="top" width="300"> |
| <h3><a href="../../../../index.htm"><img height="86" width="277" |
| alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> |
| </td> |
| |
| <td valign="top"> |
| <h1 align="center"><a href="../index.html">Boost.Python</a></h1> |
| |
| <h2 align="center">Header <boost/python/iterator.hpp></h2> |
| </td> |
| </tr> |
| </table> |
| <hr> |
| |
| <h2>Contents</h2> |
| |
| <dl class="page-index"> |
| <dt><a href="#introduction">Introduction</a></dt> |
| |
| <dt><a href="#classes">Classes</a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#iterator-spec">Class template |
| <code>iterator</code></a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#iterator-spec-synopsis">Class |
| <code>iterator</code> synopsis</a></dt> |
| |
| <dt><a href="#iterator-spec-constructors">Class template |
| <code>iterator</code> constructor</a></dt> |
| </dl> |
| </dd> |
| </dl> |
| |
| <dl class="page-index"> |
| <dt><a href="#iterators-spec">Class template |
| <code>iterators</code></a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#iterators-spec-synopsis">Class |
| <code>iterators</code> synopsis</a></dt> |
| |
| <dt><a href="#iterators-spec-types">Class template |
| <code>iterators</code> nested types</a></dt> |
| |
| <dt><a href="#iterators-spec-statics">Class template |
| <code>iterators</code> static functions</a></dt> |
| </dl> |
| </dd> |
| </dl> |
| </dd> |
| |
| <dt><a href="#functions">Functions</a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#range-spec">range</a></dt> |
| </dl> |
| </dd> |
| |
| <dt><a href="#examples">Examples</a></dt> |
| </dl> |
| <hr> |
| |
| <h2><a name="introduction"></a>Introduction</h2> |
| |
| <p><code><boost/python/iterator.hpp></code> provides types and |
| functions for creating <a href= |
| "http://www.python.org/doc/current/lib/typeiter.html">Python |
| iterators</a> from <a href= |
| "http://www.sgi.com/tech/stl/Container.html">C++ Containers</a> and <a |
| href="http://www.sgi.com/tech/stl/Iterators.html">Iterators</a>. Note |
| that if your <code>class_</code> supports random-access iterators, |
| implementing <code><a href= |
| "http://www.python.org/doc/current/ref/sequence-types.html#l2h-128">__getitem__</a></code> |
| (also known as the Sequence Protocol) may serve you better than using |
| this facility: Python will automatically create an iterator type for you |
| (see <a href= |
| "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35">iter()</a>), |
| and each access can be range-checked, leaving no possiblity of accessing |
| through an invalidated C++ iterator.</p> |
| |
| <h2><a name="classes"></a>Classes</h2> |
| |
| <h3><a name="iterator-spec"></a>Class Template <code>iterator</code></h3> |
| |
| <p>Instances of <code>iterator<C,P></code> hold a reference to a |
| callable Python object which, when invoked from Python, expects a single |
| argument <code>c</code> convertible to <code>C</code> and creates a |
| Python iterator that traverses [<code>c.begin()</code>, |
| <code>c.end()</code>). The optional <a href= |
| "CallPolicies.html">CallPolicies</a> <code>P</code> can be used to |
| control how elements are returned during iteration.</p> |
| |
| <p>In the table below, <code><b>c</b></code> is an instance of |
| <code>Container</code>.</p> |
| |
| <table border="1" summary="iterator template parameters"> |
| <tr> |
| <th>Template Parameter</th> |
| |
| <th>Requirements</th> |
| |
| <th>Semantics</th> |
| |
| <th>Default</th> |
| </tr> |
| |
| <tr> |
| <td><code>Container</code></td> |
| |
| <td>[c.begin(),c.end()) is a valid <a href= |
| "http://www.sgi.com/tech/stl/Iterators.html">Iterator range</a>.</td> |
| |
| <td>The result will convert its argument to <code>c</code> and call |
| <code>c.begin()</code> and <code>c.end()</code> to acquire iterators. |
| To invoke <code>Container</code>'s <code>const</code> |
| <code>begin()</code> and <code>end()</code> functions, make it |
| <code>const</code>.</td> |
| </tr> |
| |
| <tr> |
| <td><code>NextPolicies</code></td> |
| |
| <td>A default-constructible model of <a href= |
| "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</td> |
| |
| <td>Applied to the resulting iterators' <code>next()</code> |
| method.</td> |
| |
| <td>An unspecified model of <a href= |
| "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which |
| always makes a copy of the result of deferencing the underlying C++ |
| iterator</td> |
| </tr> |
| </table> |
| |
| <h4><a name="iterator-spec-synopsis"></a>Class Template iterator |
| synopsis</h4> |
| <pre> |
| namespace boost { namespace python |
| { |
| template <class Container |
| , class NextPolicies = <i>unspecified</i>> |
| struct iterator : <a href="object.html#object-spec">object</a> |
| { |
| iterator(); |
| }; |
| }} |
| </pre> |
| |
| <h4><a name="iterator-spec-constructors"></a>Class Template iterator |
| constructor</h4> |
| <pre> |
| iterator() |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Effects:</b></dt> |
| |
| <dd> |
| Initializes its base class with the result of: |
| <pre> |
| range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end) |
| </pre> |
| </dd> |
| |
| <dt><b>Postconditions:</b> <code>this->get()</code> points to a |
| Python callable object which creates a Python iterator as described |
| above.</dt> |
| |
| <dt><b>Rationale:</b> Provides an easy way to create iterators for the |
| common case where a C++ class being wrapped provides |
| <code>begin()</code> and <code>end()</code>.</dt> |
| </dl> |
| <!-- --> |
| |
| <h3><a name="iterators-spec"></a>Class Template |
| <code>iterators</code></h3> |
| |
| <p>A utility class template which provides a way to reliably call its |
| argument's <code>begin()</code> and <code>end()</code> member functions. |
| Note that there is no portable way to take the address of a member |
| function of a C++ standard library container, so |
| <code>iterators<></code> can be particularly helpful when wrapping |
| them.</p> |
| |
| <p>In the table below, <code><b>x</b></code> is an instance of |
| <code>C</code>.</p> |
| |
| <table border="1" summary="iterator template parameters"> |
| <tr> |
| <th>Required Valid Expression</th> |
| |
| <th>Type</th> |
| </tr> |
| |
| <tr> |
| <td><code>x.begin()</code></td> |
| |
| <td>Convertible to <code>C::const_iterator</code> if <code>C</code> |
| is a <code>const</code> type; convertible to <code>C::iterator</code> |
| otherwise.</td> |
| </tr> |
| |
| <tr> |
| <td><code>x.end()</code></td> |
| |
| <td>Convertible to <code>C::const_iterator</code> if <code>C</code> |
| is a <code>const</code> type; convertible to <code>C::iterator</code> |
| otherwise.</td> |
| </tr> |
| </table> |
| |
| <h4><a name="iterators-spec-synopsis"></a>Class Template iterators |
| synopsis</h4> |
| <pre> |
| 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); |
| }; |
| }} |
| |
| </pre> |
| |
| <h4><a name="iterators-spec-types"></a>Class Template iterators nested |
| types</h4> |
| If C is a <code>const</code> type, |
| <pre> |
| typedef typename C::const_iterator iterator; |
| </pre> |
| Otherwise: |
| <pre> |
| typedef typename C::iterator iterator; |
| </pre> |
| |
| <h4><a name="iterators-spec-statics"></a>Class Template iterators static |
| functions</h4> |
| <pre> |
| static iterator begin(C&); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Returns:</b> <code>x.begin()</code></dt> |
| </dl> |
| <pre> |
| static iterator end(C&); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Returns:</b> <code>x.end()</code></dt> |
| </dl> |
| <!-- --> |
| |
| <h2><a name="functions"></a>Functions</h2> |
| <pre> |
| <a name= |
| "range-spec">template</a> <class NextPolicies, class Target, class Accessor1, class Accessor2> |
| <a href= |
| "object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); |
| |
| template <class NextPolicies, class Accessor1, class Accessor2> |
| <a href= |
| "object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); |
| |
| template <class Accessor1, class Accessor2> |
| <a href= |
| "object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); |
| </pre> |
| |
| <dl class="range-semantics"> |
| <dt><b>Requires:</b> <code>NextPolicies</code> is a |
| default-constructible model of <a href= |
| "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</dt> |
| |
| <dt><b>Effects:</b></dt> |
| |
| <dd> |
| <dl> |
| <dt>The first form creates a Python callable object which, when |
| invoked, converts its argument to a <code>Target</code> object |
| <code>x</code>, and creates a Python iterator which traverses |
| [<code><a href= |
| "../../../bind/bind.html">bind</a>(start,_1)(x)</code>, <code><a |
| href="../../../bind/bind.html">bind</a>(finish,_1)(x)</code>), |
| applying <code>NextPolicies</code> to the iterator's |
| <code>next()</code> function.</dt> |
| |
| <dt>The second form is identical to the first, except that |
| <code>Target</code> is deduced from <code>Accessor1</code> as |
| follows:</dt> |
| |
| <dd> |
| <ol> |
| <li>If <code>Accessor1</code> is a function type, |
| <code>Target</code> is the type of its first argument.</li> |
| |
| <li>If <code>Accessor1</code> is a data member pointer of the |
| form <code>R (T::*)</code>, <code>Target</code> is |
| identical to <code>T</code>.</li> |
| |
| <li>If <code>Accessor1</code> is a member function pointer of |
| the form |
| <code>R (T::*)(</code><i>arguments...</i><code>)</code> |
| <i>cv-opt</i>, where <i>cv-opt</i> is an optional |
| <code>cv-qualifier</code>, <code>Target</code> is identical to |
| <code>T</code>.</li> |
| </ol> |
| </dd> |
| |
| <dt>The third form is identical to the second, except that |
| <code>NextPolicies</code> is an unspecified model of <a href= |
| "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which |
| always makes a copy of the result of deferencing the underlying C++ |
| iterator</dt> |
| </dl> |
| </dd> |
| |
| <dt><b>Rationale:</b> The use of <code><a href= |
| "../../../bind/bind.html">boost::bind</a>()</code> allows C++ iterators |
| to be accessed through functions, member functions or data member |
| pointers. Customization of <code>NextPolicies</code> (e.g. using |
| <code><a href= |
| "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code>) |
| is useful when it is expensive to copy sequence elements of a wrapped |
| class type. Customization of <code>Target</code> is useful when |
| <code>Accessor1</code> is a function object, or when a base class of |
| the intended target type would otherwise be deduced.</dt> |
| </dl> |
| |
| <h2><a name="examples"></a>Examples</h2> |
| <pre> |
| #include <boost/python/module.hpp> |
| #include <boost/python/class.hpp> |
| |
| #include <vector> |
| |
| using namespace boost::python; |
| BOOST_PYTHON_MODULE(demo) |
| { |
| class_<std::vector<double> >("dvec") |
| .def("__iter__", iterator<std::vector<double> >()) |
| ; |
| } |
| </pre> |
| A more comprehensive example can be found in: |
| |
| <dl> |
| <dt><code><a href= |
| "../../test/iterator.cpp">libs/python/test/iterator.cpp</a></code></dt> |
| |
| <dt><code><a href= |
| "../../test/input_iterator.cpp">libs/python/test/input_iterator.cpp</a></code></dt> |
| |
| <dt><code><a href= |
| "../../test/iterator.py">libs/python/test/input_iterator.py</a></code></dt> |
| |
| </dl> |
| <hr> |
| <p>Revised |
| <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
| 13 November, 2002 |
| <!--webbot bot="Timestamp" endspan i-checksum="39359" --> |
| </p> |
| |
| <p><i>© Copyright <a href= |
| "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> |
| </body> |
| </html> |
| |