1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Indexing support</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="../topics.html" title="Chapter 8. Topics"> 9<link rel="prev" href="pickle_support.html" title="Pickle support"> 10<link rel="next" href="../glossary.html" title="Chapter 9. Glossary"> 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="pickle_support.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../topics.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="../glossary.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="topics.indexing_support"></a><a class="link" href="indexing_support.html" title="Indexing support">Indexing support</a> 21</h2></div></div></div> 22<div class="toc"><dl class="toc"> 23<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.introduction">Introduction</a></span></dt> 24<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.the_indexing_interface">The 25 Indexing Interface</a></span></dt> 26<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.index_suite_sub_classes">index_suite 27 sub-classes</a></span></dt> 28<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.indexing_suite_class"><code class="computeroutput"><span class="identifier">indexing_suite</span></code> class</a></span></dt> 29<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.class_vector_indexing_suite">class 30 <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a></span></dt> 31<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.class_map_indexing_suite">class 32 <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a></span></dt> 33</dl></div> 34<div class="section"> 35<div class="titlepage"><div><div><h3 class="title"> 36<a name="topics.indexing_support.introduction"></a><a class="link" href="indexing_support.html#topics.indexing_support.introduction" title="Introduction">Introduction</a> 37</h3></div></div></div> 38<p> 39 Indexing is a <code class="computeroutput"><span class="identifier">Boost</span> <span class="identifier">Python</span></code> 40 facility for easy exportation of indexable C++ containers to Python. Indexable 41 containers are containers that allow random access through the <code class="computeroutput"><span class="keyword">operator</span><span class="special">[]</span></code> 42 (e.g. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>). 43 </p> 44<p> 45 While <code class="computeroutput"><span class="identifier">Boost</span> <span class="identifier">Python</span></code> 46 has all the facilities needed to expose indexable C++ containers such as 47 the ubiquitous std::vector to Python, the procedure is not as straightforward 48 as we'd like it to be. Python containers do not map easily to C++ containers. 49 Emulating Python containers in C++ (see Python Reference Manual, <a href="http://www.python.org/doc/current/ref/sequence-types.html" target="_top">Emulating 50 container types</a>) using <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> 51 is non trivial. There are a lot of issues to consider before we can map 52 a C++ container to Python. These involve implementing wrapper functions 53 for the methods <code class="computeroutput"><span class="identifier">__len__</span></code>, 54 <code class="computeroutput"><span class="identifier">__getitem__</span></code>, <code class="computeroutput"><span class="identifier">__setitem__</span></code>, <code class="computeroutput"><span class="identifier">__delitem__</span></code>, 55 <code class="computeroutput"><span class="identifier">__iter__</span></code> and <code class="computeroutput"><span class="identifier">__contains__</span></code>. 56 </p> 57<p> 58 The goals: 59 </p> 60<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 61<li class="listitem"> 62 Make indexable C++ containers behave exactly as one would expect a 63 Python container to behave. 64 </li> 65<li class="listitem"> 66<p class="simpara"> 67 Provide default reference semantics for container element indexing 68 (<code class="computeroutput"><span class="identifier">__getitem__</span></code>) such 69 that c[i] can be mutable. Require: 70 </p> 71<pre class="programlisting"><span class="identifier">val</span> <span class="special">=</span> <span class="identifier">c</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> 72<span class="identifier">c</span><span class="special">[</span><span class="identifier">i</span><span class="special">].</span><span class="identifier">m</span><span class="special">()</span> 73<span class="identifier">val</span> <span class="special">==</span> <span class="identifier">c</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> 74</pre> 75<p class="simpara"> 76 where m is a non-const (mutating) member function (method). 77 </p> 78</li> 79<li class="listitem"> 80 Return safe references from <code class="computeroutput"><span class="identifier">__getitem__</span></code> 81 such that subsequent adds and deletes to and from the container will 82 not result in dangling references (will not crash Python). 83 </li> 84<li class="listitem"> 85 Support slice indexes. 86 </li> 87<li class="listitem"> 88 Accept Python container arguments (e.g. <code class="computeroutput"><span class="identifier">lists</span></code>, 89 <code class="computeroutput"><span class="identifier">tuples</span></code>) wherever appropriate. 90 </li> 91<li class="listitem"> 92 Allow for extensibility through re-definable policy classes. 93 </li> 94<li class="listitem"> 95 Provide predefined support for the most common STL and STL-like indexable 96 containers. 97 </li> 98</ul></div> 99</div> 100<div class="section"> 101<div class="titlepage"><div><div><h3 class="title"> 102<a name="topics.indexing_support.the_indexing_interface"></a><a class="link" href="indexing_support.html#topics.indexing_support.the_indexing_interface" title="The Indexing Interface">The 103 Indexing Interface</a> 104</h3></div></div></div> 105<p> 106 The <code class="computeroutput"><span class="identifier">indexing_suite</span></code> class 107 is the base class for the management of C++ containers intended to be integrated 108 to Python. The objective is make a C++ container look and feel and behave 109 exactly as we'd expect a Python container. The class automatically wraps 110 these special Python methods (taken from the Python reference: Emulating 111 container types): 112 </p> 113<div class="variablelist"> 114<p class="title"><b></b></p> 115<dl class="variablelist"> 116<dt><span class="term">__len__(self)</span></dt> 117<dd><p> 118 Called to implement the built-in function <code class="computeroutput"><span class="identifier">len</span><span class="special">()</span></code>. Should return the length of the 119 object, an integer <code class="computeroutput"><span class="special">>=</span> <span class="number">0</span></code>. Also, an object that doesn't define 120 a <code class="computeroutput"><span class="identifier">__nonzero__</span><span class="special">()</span></code> 121 method and whose <code class="computeroutput"><span class="identifier">__len__</span><span class="special">()</span></code> method returns zero is considered 122 to be false in a Boolean context. 123 </p></dd> 124<dt><span class="term">__getitem__(self, key)</span></dt> 125<dd><p> 126 Called to implement evaluation of <code class="computeroutput"><span class="identifier">self</span><span class="special">[</span><span class="identifier">key</span><span class="special">]</span></code>. For sequence types, the accepted 127 keys should be integers and slice objects. Note that the special 128 interpretation of negative indexes (if the class wishes to emulate 129 a sequence type) is up to the <code class="computeroutput"><span class="identifier">__getitem__</span><span class="special">()</span></code> method. If key is of an inappropriate 130 type, <code class="computeroutput"><span class="identifier">TypeError</span></code> may 131 be raised; if of a value outside the set of indexes for the sequence 132 (after any special interpretation of negative values), IndexError 133 should be raised. [Note: for loops expect that an IndexError will 134 be raised for illegal indexes to allow proper detection of the end 135 of the sequence.] 136 </p></dd> 137<dt><span class="term">__setitem__(self, key, value)</span></dt> 138<dd><p> 139 Called to implement assignment to self[key]. Same note as for __getitem__(). 140 This should only be implemented for mappings if the objects support 141 changes to the values for keys, or if new keys can be added, or for 142 sequences if elements can be replaced. The same exceptions should 143 be raised for improper key values as for the __getitem__() method. 144 </p></dd> 145<dt><span class="term">__delitem__(self, key)</span></dt> 146<dd><p> 147 Called to implement deletion of self[key]. Same note as for __getitem__(). 148 This should only be implemented for mappings if the objects support 149 removal of keys, or for sequences if elements can be removed from 150 the sequence. The same exceptions should be raised for improper key 151 values as for the __getitem__() method. 152 </p></dd> 153<dt><span class="term">__iter__(self)</span></dt> 154<dd> 155<p> 156 This method is called when an iterator is required for a container. 157 This method should return a new iterator object that can iterate 158 over all the objects in the container. For mappings, it should iterate 159 over the keys of the container, and should also be made available 160 as the method iterkeys(). 161 </p> 162<p> 163 Iterator objects also need to implement this method; they are required 164 to return themselves. For more information on iterator objects, see 165 <a href="https://docs.python.org/3/library/stdtypes.html#iterator-types" target="_top">Iterator 166 Types</a> in the <a href="https://docs.python.org/3/library/index.html" target="_top">Python 167 Library Reference</a>. 168 </p> 169</dd> 170<dt><span class="term">__contains__(self, item)</span></dt> 171<dd><p> 172 Called to implement membership test operators. Should return true 173 if item is in self, false otherwise. For mapping objects, this should 174 consider the keys of the mapping rather than the values or the key-item 175 pairs. 176 </p></dd> 177</dl> 178</div> 179</div> 180<div class="section"> 181<div class="titlepage"><div><div><h3 class="title"> 182<a name="topics.indexing_support.index_suite_sub_classes"></a><a class="link" href="indexing_support.html#topics.indexing_support.index_suite_sub_classes" title="index_suite sub-classes">index_suite 183 sub-classes</a> 184</h3></div></div></div> 185<div class="toc"><dl class="toc"> 186<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.vector_index_suite">vector_index_suite</a></span></dt> 187<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.map_index_suite">map_index_suite</a></span></dt> 188</dl></div> 189<p> 190 The <code class="computeroutput"><span class="identifier">indexing_suite</span></code> is not 191 meant to be used as is. A couple of policy functions must be supplied by 192 subclasses of <code class="computeroutput"><span class="identifier">indexing_suite</span></code>. 193 However, a set of indexing_suite subclasses for the standard indexable 194 STL containers will be provided, In most cases, we can simply use the available 195 predefined suites. In some cases, we can refine the predefined suites to 196 suit our needs. 197 </p> 198<div class="section"> 199<div class="titlepage"><div><div><h4 class="title"> 200<a name="topics.indexing_support.index_suite_sub_classes.vector_index_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.vector_index_suite" title="vector_index_suite">vector_index_suite</a> 201</h4></div></div></div> 202<p> 203 The <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code> 204 class is a predefined <code class="computeroutput"><span class="identifier">indexing_suite</span></code> 205 derived class designed to wrap <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code> 206 (and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>-like [i.e. a class with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code> interface]) classes. It provides 207 all the policies required by the <code class="computeroutput"><span class="identifier">indexing_suite</span></code>. 208 </p> 209<p> 210 Example usage: 211 </p> 212<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{...};</span> 213<span class="special">...</span> 214<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="identifier">X</span><span class="special">></span> <span class="special">>(</span><span class="string">"XVec"</span><span class="special">)</span> 215 <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">vector_indexing_suite</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="identifier">X</span><span class="special">></span> <span class="special">>())</span> 216<span class="special">;</span> 217</pre> 218<p> 219 XVec is now a full-fledged Python container (see the example in full, 220 along with its python test). 221 </p> 222</div> 223<div class="section"> 224<div class="titlepage"><div><div><h4 class="title"> 225<a name="topics.indexing_support.index_suite_sub_classes.map_index_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.map_index_suite" title="map_index_suite">map_index_suite</a> 226</h4></div></div></div> 227<p> 228 The <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code> 229 class is a predefined <code class="computeroutput"><span class="identifier">indexing_suite</span></code> 230 derived class designed to wrap <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code> 231 (and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code>-like [i.e. a class with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code> interface]) classes. It provides 232 all the policies required by the <code class="computeroutput"><span class="identifier">indexing_suite</span></code>. 233 </p> 234<p> 235 Example usage: 236 </p> 237<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{...};</span> 238<span class="special">...</span> 239 240<span class="identifier">class_</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">>(</span><span class="string">"XMap"</span><span class="special">)</span> 241 <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">map_indexing_suite</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">>())</span> 242<span class="special">;</span> 243</pre> 244<p> 245 By default indexed elements are returned by proxy. This can be disabled 246 by supplying <code class="computeroutput"><span class="keyword">true</span></code> in the 247 <code class="computeroutput"><span class="identifier">NoProxy</span></code> template parameter. 248 XMap is now a full-fledged Python container (see the example in full, 249 along with its python test). 250 </p> 251</div> 252</div> 253<div class="section"> 254<div class="titlepage"><div><div><h3 class="title"> 255<a name="topics.indexing_support.indexing_suite_class"></a><a class="link" href="indexing_support.html#topics.indexing_support.indexing_suite_class" title="indexing_suite class"><code class="computeroutput"><span class="identifier">indexing_suite</span></code> class</a> 256</h3></div></div></div> 257<div class="toc"><dl class="toc"><dt><span class="section"><a href="indexing_support.html#topics.indexing_support.indexing_suite_class.derivedpolicies">DerivedPolicies</a></span></dt></dl></div> 258<div class="informaltable"><table class="table"> 259<colgroup> 260<col> 261<col> 262<col> 263<col> 264</colgroup> 265<thead><tr> 266<th> 267 <p> 268 Template Parameter 269 </p> 270 </th> 271<th> 272 <p> 273 Requirements 274 </p> 275 </th> 276<th> 277 <p> 278 Semantics 279 </p> 280 </th> 281<th> 282 <p> 283 Default 284 </p> 285 </th> 286</tr></thead> 287<tbody> 288<tr> 289<td> 290 <p> 291 Container 292 </p> 293 </td> 294<td> 295 <p> 296 A class type 297 </p> 298 </td> 299<td> 300 <p> 301 The container type to be wrapped to Python. 302 </p> 303 </td> 304<td> 305 </td> 306</tr> 307<tr> 308<td> 309 <p> 310 DerivedPolicies 311 </p> 312 </td> 313<td> 314 <p> 315 A subclass of indexing_suite 316 </p> 317 </td> 318<td> 319 <p> 320 Derived classes provide the policy hooks. See DerivedPolicies 321 below. 322 </p> 323 </td> 324<td> 325 </td> 326</tr> 327<tr> 328<td> 329 <p> 330 NoProxy 331 </p> 332 </td> 333<td> 334 <p> 335 A boolean 336 </p> 337 </td> 338<td> 339 <p> 340 By default indexed elements have Python reference semantics and 341 are returned by proxy. This can be disabled by supplying true 342 in the NoProxy template parameter. 343 </p> 344 </td> 345<td> 346 <p> 347 false 348 </p> 349 </td> 350</tr> 351<tr> 352<td> 353 <p> 354 NoSlice 355 </p> 356 </td> 357<td> 358 <p> 359 A boolean 360 </p> 361 </td> 362<td> 363 <p> 364 Do not allow slicing. 365 </p> 366 </td> 367<td> 368 <p> 369 false 370 </p> 371 </td> 372</tr> 373<tr> 374<td> 375 <p> 376 Data 377 </p> 378 </td> 379<td> 380 </td> 381<td> 382 <p> 383 The container's data type. 384 </p> 385 </td> 386<td> 387 <p> 388 Container::value_type 389 </p> 390 </td> 391</tr> 392<tr> 393<td> 394 <p> 395 Index 396 </p> 397 </td> 398<td> 399 </td> 400<td> 401 <p> 402 The container's index type. 403 </p> 404 </td> 405<td> 406 <p> 407 Container::size_type 408 </p> 409 </td> 410</tr> 411<tr> 412<td> 413 <p> 414 Key 415 </p> 416 </td> 417<td> 418 </td> 419<td> 420 <p> 421 The container's key type. 422 </p> 423 </td> 424<td> 425 <p> 426 Container::value_type 427 </p> 428 </td> 429</tr> 430</tbody> 431</table></div> 432<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> 433 <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span><span class="special">,</span> 434 <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> 435 <span class="keyword">bool</span> <span class="identifier">NoSlice</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> 436 <span class="keyword">class</span> <span class="identifier">Data</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">,</span> 437 <span class="keyword">class</span> <span class="identifier">Index</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span><span class="special">,</span> 438 <span class="keyword">class</span> <span class="identifier">Key</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">></span> 439<span class="keyword">class</span> <span class="identifier">indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified</span> 440<span class="special">{</span> 441<span class="keyword">public</span><span class="special">:</span> 442 <span class="identifier">indexing_suite</span><span class="special">();</span> <span class="comment">// default constructor</span> 443<span class="special">}</span> 444</pre> 445<div class="section"> 446<div class="titlepage"><div><div><h4 class="title"> 447<a name="topics.indexing_support.indexing_suite_class.derivedpolicies"></a><a class="link" href="indexing_support.html#topics.indexing_support.indexing_suite_class.derivedpolicies" title="DerivedPolicies">DerivedPolicies</a> 448</h4></div></div></div> 449<p> 450 Derived classes provide the hooks needed by the indexing_suite: 451 </p> 452<pre class="programlisting"><span class="identifier">data_type</span><span class="special">&</span> 453<span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> 454 455<span class="keyword">static</span> <span class="identifier">object</span> 456<span class="identifier">get_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> 457 458<span class="keyword">static</span> <span class="keyword">void</span> 459<span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> 460 461<span class="keyword">static</span> <span class="keyword">void</span> 462<span class="identifier">set_slice</span><span class="special">(</span> 463 <span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> 464 <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span> 465<span class="special">);</span> 466 467<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Iter</span><span class="special">></span> 468<span class="keyword">static</span> <span class="keyword">void</span> 469<span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> 470 <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">last</span> 471<span class="special">);</span> 472 473<span class="keyword">static</span> <span class="keyword">void</span> 474<span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> 475 476<span class="keyword">static</span> <span class="keyword">void</span> 477<span class="identifier">delete_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> 478 479<span class="keyword">static</span> <span class="identifier">size_t</span> 480<span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">);</span> 481 482<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 483<span class="keyword">static</span> <span class="keyword">bool</span> 484<span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span> 485 486<span class="keyword">static</span> <span class="identifier">index_type</span> 487<span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">i</span><span class="special">);</span> 488 489<span class="keyword">static</span> <span class="identifier">index_type</span> 490<span class="identifier">adjust_index</span><span class="special">(</span><span class="identifier">index_type</span> <span class="identifier">current</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> 491 <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">len</span><span class="special">);</span> 492</pre> 493<p> 494 Most of these policies are self explanatory. However, convert_index and 495 adjust_index deserve some explanation. 496 </p> 497<p> 498 convert_index converts a Python index into a C++ index that the container 499 can handle. For instance, negative indexes in Python, by convention, 500 start counting from the right(e.g. C<span class="strikethrough">1</span> 501 indexes the rightmost element in C). convert_index should handle the 502 necessary conversion for the C++ container (e.g. convert -1 to C.size()-1). 503 convert_index should also be able to convert the type of the index (A 504 dynamic Python type) to the actual type that the C++ container expects. 505 </p> 506<p> 507 When a container expands or contracts, held indexes to its elements must 508 be adjusted to follow the movement of data. For instance, if we erase 509 3 elements, starting from index 0 from a 5 element vector, what used 510 to be at index 4 will now be at index 1: 511 </p> 512<pre class="programlisting"><span class="special">[</span><span class="identifier">a</span><span class="special">][</span><span class="identifier">b</span><span class="special">][</span><span class="identifier">c</span><span class="special">][</span><span class="identifier">d</span><span class="special">][</span><span class="identifier">e</span><span class="special">]</span> <span class="special">---></span> <span class="special">[</span><span class="identifier">d</span><span class="special">][</span><span class="identifier">e</span><span class="special">]</span> 513 <span class="special">^</span> <span class="special">^</span> 514 <span class="number">4</span> <span class="number">1</span> 515</pre> 516<p> 517 adjust_index takes care of the adjustment. Given a current index, the 518 function should return the adjusted index when data in the container 519 at index from..to is replaced by len elements. 520 </p> 521</div> 522</div> 523<div class="section"> 524<div class="titlepage"><div><div><h3 class="title"> 525<a name="topics.indexing_support.class_vector_indexing_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.class_vector_indexing_suite" title="class vector_indexing_suite">class 526 <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a> 527</h3></div></div></div> 528<div class="informaltable"><table class="table"> 529<colgroup> 530<col> 531<col> 532<col> 533<col> 534</colgroup> 535<thead><tr> 536<th> 537 <p> 538 Template Parameter 539 </p> 540 </th> 541<th> 542 <p> 543 Requirements 544 </p> 545 </th> 546<th> 547 <p> 548 Semantics 549 </p> 550 </th> 551<th> 552 <p> 553 Default 554 </p> 555 </th> 556</tr></thead> 557<tbody> 558<tr> 559<td> 560 <p> 561 Container 562 </p> 563 </td> 564<td> 565 <p> 566 A class type 567 </p> 568 </td> 569<td> 570 <p> 571 The container type to be wrapped to Python. 572 </p> 573 </td> 574<td> 575 </td> 576</tr> 577<tr> 578<td> 579 <p> 580 NoProxy 581 </p> 582 </td> 583<td> 584 <p> 585 A boolean 586 </p> 587 </td> 588<td> 589 <p> 590 By default indexed elements have Python reference semantics and 591 are returned by proxy. This can be disabled by supplying true 592 in the NoProxy template parameter. 593 </p> 594 </td> 595<td> 596 <p> 597 false 598 </p> 599 </td> 600</tr> 601<tr> 602<td> 603 <p> 604 DerivedPolicies 605 </p> 606 </td> 607<td> 608 <p> 609 A subclass of indexing_suite 610 </p> 611 </td> 612<td> 613 <p> 614 The vector_indexing_suite may still be derived to further tweak 615 any of the predefined policies. Static polymorphism through CRTP 616 (James Coplien. "Curiously Recurring Template Pattern". 617 C++ Report, Feb. 1995) enables the base indexing_suite class 618 to call policy function of the most derived class 619 </p> 620 </td> 621<td> 622 </td> 623</tr> 624</tbody> 625</table></div> 626<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> 627 <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> 628 <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span> <span class="special">=</span> <span class="identifier">unspecified_default</span><span class="special">></span> 629<span class="keyword">class</span> <span class="identifier">vector_indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified_base</span> 630<span class="special">{</span> 631<span class="keyword">public</span><span class="special">:</span> 632 633 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">data_type</span><span class="special">;</span> 634 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">key_type</span><span class="special">;</span> 635 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">index_type</span><span class="special">;</span> 636 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">size_type</span><span class="special">;</span> 637 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span> 638 639 <span class="identifier">data_type</span><span class="special">&</span> 640 <span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> 641 642 <span class="keyword">static</span> <span class="identifier">object</span> 643 <span class="identifier">get_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> 644 645 <span class="keyword">static</span> <span class="keyword">void</span> 646 <span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> 647 648 <span class="keyword">static</span> <span class="keyword">void</span> 649 <span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> 650 <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> 651 652 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Iter</span><span class="special">></span> 653 <span class="keyword">static</span> <span class="keyword">void</span> 654 <span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> 655 <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">last</span><span class="special">);</span> 656 657 <span class="keyword">static</span> <span class="keyword">void</span> 658 <span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> 659 660 <span class="keyword">static</span> <span class="keyword">void</span> 661 <span class="identifier">delete_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> 662 663 <span class="keyword">static</span> <span class="identifier">size_t</span> 664 <span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">);</span> 665 666 <span class="keyword">static</span> <span class="keyword">bool</span> 667 <span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> 668 669 <span class="keyword">static</span> <span class="identifier">index_type</span> 670 <span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">i</span><span class="special">);</span> 671 672 <span class="keyword">static</span> <span class="identifier">index_type</span> 673 <span class="identifier">adjust_index</span><span class="special">(</span><span class="identifier">index_type</span> <span class="identifier">current</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> 674 <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">len</span><span class="special">);</span> 675<span class="special">};</span> 676</pre> 677</div> 678<div class="section"> 679<div class="titlepage"><div><div><h3 class="title"> 680<a name="topics.indexing_support.class_map_indexing_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.class_map_indexing_suite" title="class map_indexing_suite">class 681 <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a> 682</h3></div></div></div> 683<div class="informaltable"><table class="table"> 684<colgroup> 685<col> 686<col> 687<col> 688<col> 689</colgroup> 690<thead><tr> 691<th> 692 <p> 693 Template Parameter 694 </p> 695 </th> 696<th> 697 <p> 698 Requirements 699 </p> 700 </th> 701<th> 702 <p> 703 Semantics 704 </p> 705 </th> 706<th> 707 <p> 708 Default 709 </p> 710 </th> 711</tr></thead> 712<tbody> 713<tr> 714<td> 715 <p> 716 Container 717 </p> 718 </td> 719<td> 720 <p> 721 A class type 722 </p> 723 </td> 724<td> 725 <p> 726 The container type to be wrapped to Python. 727 </p> 728 </td> 729<td> 730 </td> 731</tr> 732<tr> 733<td> 734 <p> 735 NoProxy 736 </p> 737 </td> 738<td> 739 <p> 740 A boolean 741 </p> 742 </td> 743<td> 744 <p> 745 By default indexed elements have Python reference semantics and 746 are returned by proxy. This can be disabled by supplying true 747 in the NoProxy template parameter. 748 </p> 749 </td> 750<td> 751 <p> 752 false 753 </p> 754 </td> 755</tr> 756<tr> 757<td> 758 <p> 759 DerivedPolicies 760 </p> 761 </td> 762<td> 763 <p> 764 A subclass of indexing_suite 765 </p> 766 </td> 767<td> 768 <p> 769 The vector_indexing_suite may still be derived to further tweak 770 any of the predefined policies. Static polymorphism through CRTP 771 (James Coplien. "Curiously Recurring Template Pattern". 772 C++ Report, Feb. 1995) enables the base indexing_suite class 773 to call policy function of the most derived class 774 </p> 775 </td> 776<td> 777 </td> 778</tr> 779</tbody> 780</table></div> 781<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> 782 <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> 783 <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span> <span class="special">=</span> <span class="identifier">unspecified_default</span><span class="special">></span> 784<span class="keyword">class</span> <span class="identifier">map_indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified_base</span> 785<span class="special">{</span> 786<span class="keyword">public</span><span class="special">:</span> 787 788 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">value_type</span><span class="special">;</span> 789 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">::</span><span class="identifier">second_type</span> <span class="identifier">data_type</span><span class="special">;</span> 790 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">key_type</span> <span class="identifier">key_type</span><span class="special">;</span> 791 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">key_type</span> <span class="identifier">index_type</span><span class="special">;</span> 792 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">size_type</span><span class="special">;</span> 793 <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span> 794 795 <span class="keyword">static</span> <span class="identifier">data_type</span><span class="special">&</span> 796 <span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> 797 798 <span class="keyword">static</span> <span class="keyword">void</span> 799 <span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> 800 801 <span class="keyword">static</span> <span class="keyword">void</span> 802 <span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> 803 804 <span class="keyword">static</span> <span class="identifier">size_t</span> 805 <span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">);</span> 806 807 <span class="keyword">static</span> <span class="keyword">bool</span> 808 <span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> 809 810 <span class="keyword">static</span> <span class="keyword">bool</span> 811 <span class="identifier">compare_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">b</span><span class="special">);</span> 812 813 <span class="keyword">static</span> <span class="identifier">index_type</span> 814 <span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">i</span><span class="special">);</span> 815<span class="special">};</span> 816</pre> 817</div> 818</div> 819<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 820<td align="left"></td> 821<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> 822 Distributed under the Boost Software License, Version 1.0. (See accompanying 823 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> 824 </p> 825</div></td> 826</tr></table> 827<hr> 828<div class="spirit-nav"> 829<a accesskey="p" href="pickle_support.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../topics.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="../glossary.html"><img src="../../images/next.png" alt="Next"></a> 830</div> 831</body> 832</html> 833
