| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|---|
| 2 | |
|---|
| 3 | <!-- Copyright David Abrahams 2006. Distributed under the Boost --> |
|---|
| 4 | <!-- Software License, Version 1.0. (See accompanying --> |
|---|
| 5 | <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> |
|---|
| 6 | <html> |
|---|
| 7 | <head> |
|---|
| 8 | <meta name="generator" content= |
|---|
| 9 | "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> |
|---|
| 10 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 11 | <link rel="stylesheet" type="text/css" href="../boost.css"> |
|---|
| 12 | |
|---|
| 13 | <title>Boost.Python - <boost/python/iterator.hpp></title> |
|---|
| 14 | </head> |
|---|
| 15 | |
|---|
| 16 | <body> |
|---|
| 17 | <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
|---|
| 18 | "header"> |
|---|
| 19 | <tr> |
|---|
| 20 | <td valign="top" width="300"> |
|---|
| 21 | <h3><a href="../../../../index.htm"><img height="86" width="277" |
|---|
| 22 | alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> |
|---|
| 23 | </td> |
|---|
| 24 | |
|---|
| 25 | <td valign="top"> |
|---|
| 26 | <h1 align="center"><a href="../index.html">Boost.Python</a></h1> |
|---|
| 27 | |
|---|
| 28 | <h2 align="center">Header <boost/python/iterator.hpp></h2> |
|---|
| 29 | </td> |
|---|
| 30 | </tr> |
|---|
| 31 | </table> |
|---|
| 32 | <hr> |
|---|
| 33 | |
|---|
| 34 | <h2>Contents</h2> |
|---|
| 35 | |
|---|
| 36 | <dl class="page-index"> |
|---|
| 37 | <dt><a href="#introduction">Introduction</a></dt> |
|---|
| 38 | |
|---|
| 39 | <dt><a href="#classes">Classes</a></dt> |
|---|
| 40 | |
|---|
| 41 | <dd> |
|---|
| 42 | <dl class="page-index"> |
|---|
| 43 | <dt><a href="#iterator-spec">Class template |
|---|
| 44 | <code>iterator</code></a></dt> |
|---|
| 45 | |
|---|
| 46 | <dd> |
|---|
| 47 | <dl class="page-index"> |
|---|
| 48 | <dt><a href="#iterator-spec-synopsis">Class |
|---|
| 49 | <code>iterator</code> synopsis</a></dt> |
|---|
| 50 | |
|---|
| 51 | <dt><a href="#iterator-spec-constructors">Class template |
|---|
| 52 | <code>iterator</code> constructor</a></dt> |
|---|
| 53 | </dl> |
|---|
| 54 | </dd> |
|---|
| 55 | </dl> |
|---|
| 56 | |
|---|
| 57 | <dl class="page-index"> |
|---|
| 58 | <dt><a href="#iterators-spec">Class template |
|---|
| 59 | <code>iterators</code></a></dt> |
|---|
| 60 | |
|---|
| 61 | <dd> |
|---|
| 62 | <dl class="page-index"> |
|---|
| 63 | <dt><a href="#iterators-spec-synopsis">Class |
|---|
| 64 | <code>iterators</code> synopsis</a></dt> |
|---|
| 65 | |
|---|
| 66 | <dt><a href="#iterators-spec-types">Class template |
|---|
| 67 | <code>iterators</code> nested types</a></dt> |
|---|
| 68 | |
|---|
| 69 | <dt><a href="#iterators-spec-statics">Class template |
|---|
| 70 | <code>iterators</code> static functions</a></dt> |
|---|
| 71 | </dl> |
|---|
| 72 | </dd> |
|---|
| 73 | </dl> |
|---|
| 74 | </dd> |
|---|
| 75 | |
|---|
| 76 | <dt><a href="#functions">Functions</a></dt> |
|---|
| 77 | |
|---|
| 78 | <dd> |
|---|
| 79 | <dl class="page-index"> |
|---|
| 80 | <dt><a href="#range-spec">range</a></dt> |
|---|
| 81 | </dl> |
|---|
| 82 | </dd> |
|---|
| 83 | |
|---|
| 84 | <dt><a href="#examples">Examples</a></dt> |
|---|
| 85 | </dl> |
|---|
| 86 | <hr> |
|---|
| 87 | |
|---|
| 88 | <h2><a name="introduction"></a>Introduction</h2> |
|---|
| 89 | |
|---|
| 90 | <p><code><boost/python/iterator.hpp></code> provides types and |
|---|
| 91 | functions for creating <a href= |
|---|
| 92 | "http://www.python.org/doc/current/lib/typeiter.html">Python |
|---|
| 93 | iterators</a> from <a href= |
|---|
| 94 | "http://www.sgi.com/tech/stl/Container.html">C++ Containers</a> and <a |
|---|
| 95 | href="http://www.sgi.com/tech/stl/Iterators.html">Iterators</a>. Note |
|---|
| 96 | that if your <code>class_</code> supports random-access iterators, |
|---|
| 97 | implementing <code><a href= |
|---|
| 98 | "http://www.python.org/doc/current/ref/sequence-types.html#l2h-128">__getitem__</a></code> |
|---|
| 99 | (also known as the Sequence Protocol) may serve you better than using |
|---|
| 100 | this facility: Python will automatically create an iterator type for you |
|---|
| 101 | (see <a href= |
|---|
| 102 | "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35">iter()</a>), |
|---|
| 103 | and each access can be range-checked, leaving no possiblity of accessing |
|---|
| 104 | through an invalidated C++ iterator.</p> |
|---|
| 105 | |
|---|
| 106 | <h2><a name="classes"></a>Classes</h2> |
|---|
| 107 | |
|---|
| 108 | <h3><a name="iterator-spec"></a>Class Template <code>iterator</code></h3> |
|---|
| 109 | |
|---|
| 110 | <p>Instances of <code>iterator<C,P></code> hold a reference to a |
|---|
| 111 | callable Python object which, when invoked from Python, expects a single |
|---|
| 112 | argument <code>c</code> convertible to <code>C</code> and creates a |
|---|
| 113 | Python iterator that traverses [<code>c.begin()</code>, |
|---|
| 114 | <code>c.end()</code>). The optional <a href= |
|---|
| 115 | "CallPolicies.html">CallPolicies</a> <code>P</code> can be used to |
|---|
| 116 | control how elements are returned during iteration.</p> |
|---|
| 117 | |
|---|
| 118 | <p>In the table below, <code><b>c</b></code> is an instance of |
|---|
| 119 | <code>Container</code>.</p> |
|---|
| 120 | |
|---|
| 121 | <table border="1" summary="iterator template parameters"> |
|---|
| 122 | <tr> |
|---|
| 123 | <th>Template Parameter</th> |
|---|
| 124 | |
|---|
| 125 | <th>Requirements</th> |
|---|
| 126 | |
|---|
| 127 | <th>Semantics</th> |
|---|
| 128 | |
|---|
| 129 | <th>Default</th> |
|---|
| 130 | </tr> |
|---|
| 131 | |
|---|
| 132 | <tr> |
|---|
| 133 | <td><code>Container</code></td> |
|---|
| 134 | |
|---|
| 135 | <td>[c.begin(),c.end()) is a valid <a href= |
|---|
| 136 | "http://www.sgi.com/tech/stl/Iterators.html">Iterator range</a>.</td> |
|---|
| 137 | |
|---|
| 138 | <td>The result will convert its argument to <code>c</code> and call |
|---|
| 139 | <code>c.begin()</code> and <code>c.end()</code> to acquire iterators. |
|---|
| 140 | To invoke <code>Container</code>'s <code>const</code> |
|---|
| 141 | <code>begin()</code> and <code>end()</code> functions, make it |
|---|
| 142 | <code>const</code>.</td> |
|---|
| 143 | </tr> |
|---|
| 144 | |
|---|
| 145 | <tr> |
|---|
| 146 | <td><code>NextPolicies</code></td> |
|---|
| 147 | |
|---|
| 148 | <td>A default-constructible model of <a href= |
|---|
| 149 | "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</td> |
|---|
| 150 | |
|---|
| 151 | <td>Applied to the resulting iterators' <code>next()</code> |
|---|
| 152 | method.</td> |
|---|
| 153 | |
|---|
| 154 | <td>An unspecified model of <a href= |
|---|
| 155 | "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which |
|---|
| 156 | always makes a copy of the result of deferencing the underlying C++ |
|---|
| 157 | iterator</td> |
|---|
| 158 | </tr> |
|---|
| 159 | </table> |
|---|
| 160 | |
|---|
| 161 | <h4><a name="iterator-spec-synopsis"></a>Class Template iterator |
|---|
| 162 | synopsis</h4> |
|---|
| 163 | <pre> |
|---|
| 164 | namespace boost { namespace python |
|---|
| 165 | { |
|---|
| 166 | template <class Container |
|---|
| 167 | , class NextPolicies = <i>unspecified</i>> |
|---|
| 168 | struct iterator : <a href="object.html#object-spec">object</a> |
|---|
| 169 | { |
|---|
| 170 | iterator(); |
|---|
| 171 | }; |
|---|
| 172 | }} |
|---|
| 173 | </pre> |
|---|
| 174 | |
|---|
| 175 | <h4><a name="iterator-spec-constructors"></a>Class Template iterator |
|---|
| 176 | constructor</h4> |
|---|
| 177 | <pre> |
|---|
| 178 | iterator() |
|---|
| 179 | </pre> |
|---|
| 180 | |
|---|
| 181 | <dl class="function-semantics"> |
|---|
| 182 | <dt><b>Effects:</b></dt> |
|---|
| 183 | |
|---|
| 184 | <dd> |
|---|
| 185 | Initializes its base class with the result of: |
|---|
| 186 | <pre> |
|---|
| 187 | range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end) |
|---|
| 188 | </pre> |
|---|
| 189 | </dd> |
|---|
| 190 | |
|---|
| 191 | <dt><b>Postconditions:</b> <code>this->get()</code> points to a |
|---|
| 192 | Python callable object which creates a Python iterator as described |
|---|
| 193 | above.</dt> |
|---|
| 194 | |
|---|
| 195 | <dt><b>Rationale:</b> Provides an easy way to create iterators for the |
|---|
| 196 | common case where a C++ class being wrapped provides |
|---|
| 197 | <code>begin()</code> and <code>end()</code>.</dt> |
|---|
| 198 | </dl> |
|---|
| 199 | <!-- --> |
|---|
| 200 | |
|---|
| 201 | <h3><a name="iterators-spec"></a>Class Template |
|---|
| 202 | <code>iterators</code></h3> |
|---|
| 203 | |
|---|
| 204 | <p>A utility class template which provides a way to reliably call its |
|---|
| 205 | argument's <code>begin()</code> and <code>end()</code> member functions. |
|---|
| 206 | Note that there is no portable way to take the address of a member |
|---|
| 207 | function of a C++ standard library container, so |
|---|
| 208 | <code>iterators<></code> can be particularly helpful when wrapping |
|---|
| 209 | them.</p> |
|---|
| 210 | |
|---|
| 211 | <p>In the table below, <code><b>x</b></code> is an instance of |
|---|
| 212 | <code>C</code>.</p> |
|---|
| 213 | |
|---|
| 214 | <table border="1" summary="iterator template parameters"> |
|---|
| 215 | <tr> |
|---|
| 216 | <th>Required Valid Expression</th> |
|---|
| 217 | |
|---|
| 218 | <th>Type</th> |
|---|
| 219 | </tr> |
|---|
| 220 | |
|---|
| 221 | <tr> |
|---|
| 222 | <td><code>x.begin()</code></td> |
|---|
| 223 | |
|---|
| 224 | <td>Convertible to <code>C::const_iterator</code> if <code>C</code> |
|---|
| 225 | is a <code>const</code> type; convertible to <code>C::iterator</code> |
|---|
| 226 | otherwise.</td> |
|---|
| 227 | </tr> |
|---|
| 228 | |
|---|
| 229 | <tr> |
|---|
| 230 | <td><code>x.end()</code></td> |
|---|
| 231 | |
|---|
| 232 | <td>Convertible to <code>C::const_iterator</code> if <code>C</code> |
|---|
| 233 | is a <code>const</code> type; convertible to <code>C::iterator</code> |
|---|
| 234 | otherwise.</td> |
|---|
| 235 | </tr> |
|---|
| 236 | </table> |
|---|
| 237 | |
|---|
| 238 | <h4><a name="iterators-spec-synopsis"></a>Class Template iterators |
|---|
| 239 | synopsis</h4> |
|---|
| 240 | <pre> |
|---|
| 241 | namespace boost { namespace python |
|---|
| 242 | { |
|---|
| 243 | template <class C> |
|---|
| 244 | struct iterators |
|---|
| 245 | { |
|---|
| 246 | typedef typename C::[const_]iterator iterator; |
|---|
| 247 | static iterator begin(C& x); |
|---|
| 248 | static iterator end(C& x); |
|---|
| 249 | }; |
|---|
| 250 | }} |
|---|
| 251 | |
|---|
| 252 | </pre> |
|---|
| 253 | |
|---|
| 254 | <h4><a name="iterators-spec-types"></a>Class Template iterators nested |
|---|
| 255 | types</h4> |
|---|
| 256 | If C is a <code>const</code> type, |
|---|
| 257 | <pre> |
|---|
| 258 | typedef typename C::const_iterator iterator; |
|---|
| 259 | </pre> |
|---|
| 260 | Otherwise: |
|---|
| 261 | <pre> |
|---|
| 262 | typedef typename C::iterator iterator; |
|---|
| 263 | </pre> |
|---|
| 264 | |
|---|
| 265 | <h4><a name="iterators-spec-statics"></a>Class Template iterators static |
|---|
| 266 | functions</h4> |
|---|
| 267 | <pre> |
|---|
| 268 | static iterator begin(C&); |
|---|
| 269 | </pre> |
|---|
| 270 | |
|---|
| 271 | <dl class="function-semantics"> |
|---|
| 272 | <dt><b>Returns:</b> <code>x.begin()</code></dt> |
|---|
| 273 | </dl> |
|---|
| 274 | <pre> |
|---|
| 275 | static iterator end(C&); |
|---|
| 276 | </pre> |
|---|
| 277 | |
|---|
| 278 | <dl class="function-semantics"> |
|---|
| 279 | <dt><b>Returns:</b> <code>x.end()</code></dt> |
|---|
| 280 | </dl> |
|---|
| 281 | <!-- --> |
|---|
| 282 | |
|---|
| 283 | <h2><a name="functions"></a>Functions</h2> |
|---|
| 284 | <pre> |
|---|
| 285 | <a name= |
|---|
| 286 | "range-spec">template</a> <class NextPolicies, class Target, class Accessor1, class Accessor2> |
|---|
| 287 | <a href= |
|---|
| 288 | "object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); |
|---|
| 289 | |
|---|
| 290 | template <class NextPolicies, class Accessor1, class Accessor2> |
|---|
| 291 | <a href= |
|---|
| 292 | "object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); |
|---|
| 293 | |
|---|
| 294 | template <class Accessor1, class Accessor2> |
|---|
| 295 | <a href= |
|---|
| 296 | "object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); |
|---|
| 297 | </pre> |
|---|
| 298 | |
|---|
| 299 | <dl class="range-semantics"> |
|---|
| 300 | <dt><b>Requires:</b> <code>NextPolicies</code> is a |
|---|
| 301 | default-constructible model of <a href= |
|---|
| 302 | "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</dt> |
|---|
| 303 | |
|---|
| 304 | <dt><b>Effects:</b></dt> |
|---|
| 305 | |
|---|
| 306 | <dd> |
|---|
| 307 | <dl> |
|---|
| 308 | <dt>The first form creates a Python callable object which, when |
|---|
| 309 | invoked, converts its argument to a <code>Target</code> object |
|---|
| 310 | <code>x</code>, and creates a Python iterator which traverses |
|---|
| 311 | [<code><a href= |
|---|
| 312 | "../../../bind/bind.html">bind</a>(start,_1)(x)</code>, <code><a |
|---|
| 313 | href="../../../bind/bind.html">bind</a>(finish,_1)(x)</code>), |
|---|
| 314 | applying <code>NextPolicies</code> to the iterator's |
|---|
| 315 | <code>next()</code> function.</dt> |
|---|
| 316 | |
|---|
| 317 | <dt>The second form is identical to the first, except that |
|---|
| 318 | <code>Target</code> is deduced from <code>Accessor1</code> as |
|---|
| 319 | follows:</dt> |
|---|
| 320 | |
|---|
| 321 | <dd> |
|---|
| 322 | <ol> |
|---|
| 323 | <li>If <code>Accessor1</code> is a function type, |
|---|
| 324 | <code>Target</code> is the type of its first argument.</li> |
|---|
| 325 | |
|---|
| 326 | <li>If <code>Accessor1</code> is a data member pointer of the |
|---|
| 327 | form <code>R (T::*)</code>, <code>Target</code> is |
|---|
| 328 | identical to <code>T</code>.</li> |
|---|
| 329 | |
|---|
| 330 | <li>If <code>Accessor1</code> is a member function pointer of |
|---|
| 331 | the form |
|---|
| 332 | <code>R (T::*)(</code><i>arguments...</i><code>)</code> |
|---|
| 333 | <i>cv-opt</i>, where <i>cv-opt</i> is an optional |
|---|
| 334 | <code>cv-qualifier</code>, <code>Target</code> is identical to |
|---|
| 335 | <code>T</code>.</li> |
|---|
| 336 | </ol> |
|---|
| 337 | </dd> |
|---|
| 338 | |
|---|
| 339 | <dt>The third form is identical to the second, except that |
|---|
| 340 | <code>NextPolicies</code> is an unspecified model of <a href= |
|---|
| 341 | "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which |
|---|
| 342 | always makes a copy of the result of deferencing the underlying C++ |
|---|
| 343 | iterator</dt> |
|---|
| 344 | </dl> |
|---|
| 345 | </dd> |
|---|
| 346 | |
|---|
| 347 | <dt><b>Rationale:</b> The use of <code><a href= |
|---|
| 348 | "../../../bind/bind.html">boost::bind</a>()</code> allows C++ iterators |
|---|
| 349 | to be accessed through functions, member functions or data member |
|---|
| 350 | pointers. Customization of <code>NextPolicies</code> (e.g. using |
|---|
| 351 | <code><a href= |
|---|
| 352 | "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code>) |
|---|
| 353 | is useful when it is expensive to copy sequence elements of a wrapped |
|---|
| 354 | class type. Customization of <code>Target</code> is useful when |
|---|
| 355 | <code>Accessor1</code> is a function object, or when a base class of |
|---|
| 356 | the intended target type would otherwise be deduced.</dt> |
|---|
| 357 | </dl> |
|---|
| 358 | |
|---|
| 359 | <h2><a name="examples"></a>Examples</h2> |
|---|
| 360 | <pre> |
|---|
| 361 | #include <boost/python/module.hpp> |
|---|
| 362 | #include <boost/python/class.hpp> |
|---|
| 363 | |
|---|
| 364 | #include <vector> |
|---|
| 365 | |
|---|
| 366 | using namespace boost::python; |
|---|
| 367 | BOOST_PYTHON_MODULE(demo) |
|---|
| 368 | { |
|---|
| 369 | class_<std::vector<double> >("dvec") |
|---|
| 370 | .def("__iter__", iterator<std::vector<double> >()) |
|---|
| 371 | ; |
|---|
| 372 | } |
|---|
| 373 | </pre> |
|---|
| 374 | A more comprehensive example can be found in: |
|---|
| 375 | |
|---|
| 376 | <dl> |
|---|
| 377 | <dt><code><a href= |
|---|
| 378 | "../../test/iterator.cpp">libs/python/test/iterator.cpp</a></code></dt> |
|---|
| 379 | |
|---|
| 380 | <dt><code><a href= |
|---|
| 381 | "../../test/input_iterator.cpp">libs/python/test/input_iterator.cpp</a></code></dt> |
|---|
| 382 | |
|---|
| 383 | <dt><code><a href= |
|---|
| 384 | "../../test/iterator.py">libs/python/test/input_iterator.py</a></code></dt> |
|---|
| 385 | |
|---|
| 386 | </dl> |
|---|
| 387 | <hr> |
|---|
| 388 | <p>Revised |
|---|
| 389 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
|---|
| 390 | 13 November, 2002 |
|---|
| 391 | <!--webbot bot="Timestamp" endspan i-checksum="39359" --> |
|---|
| 392 | </p> |
|---|
| 393 | |
|---|
| 394 | <p><i>© Copyright <a href= |
|---|
| 395 | "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> |
|---|
| 396 | </body> |
|---|
| 397 | </html> |
|---|
| 398 | |
|---|
