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