devn00b
/
EQ2EMu


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832
							<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Indexing support</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Boost.Python Reference Manual">
<link rel="up" href="../topics.html" title="Chapter&#160;8.&#160;Topics">
<link rel="prev" href="pickle_support.html" title="Pickle support">
<link rel="next" href="../glossary.html" title="Chapter&#160;9.&#160;Glossary">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="topics.indexing_support"></a><a class="link" href="indexing_support.html" title="Indexing support">Indexing support</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.the_indexing_interface">The
        Indexing Interface</a></span></dt>
<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.index_suite_sub_classes">index_suite
        sub-classes</a></span></dt>
<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>
<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.class_vector_indexing_suite">class
        <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a></span></dt>
<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.class_map_indexing_suite">class
        <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="topics.indexing_support.introduction"></a><a class="link" href="indexing_support.html#topics.indexing_support.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
          Indexing is a <code class="computeroutput"><span class="identifier">Boost</span> <span class="identifier">Python</span></code>
          facility for easy exportation of indexable C++ containers to Python. Indexable
          containers are containers that allow random access through the <code class="computeroutput"><span class="keyword">operator</span><span class="special">[]</span></code>
          (e.g. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>).
        </p>
<p>
          While <code class="computeroutput"><span class="identifier">Boost</span> <span class="identifier">Python</span></code>
          has all the facilities needed to expose indexable C++ containers such as
          the ubiquitous std::vector to Python, the procedure is not as straightforward
          as we'd like it to be. Python containers do not map easily to C++ containers.
          Emulating Python containers in C++ (see Python Reference Manual, <a href="http://www.python.org/doc/current/ref/sequence-types.html" target="_top">Emulating
          container types</a>) using <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code>
          is non trivial. There are a lot of issues to consider before we can map
          a C++ container to Python. These involve implementing wrapper functions
          for the methods <code class="computeroutput"><span class="identifier">__len__</span></code>,
          <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>,
          <code class="computeroutput"><span class="identifier">__iter__</span></code> and <code class="computeroutput"><span class="identifier">__contains__</span></code>.
        </p>
<p>
          The goals:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              Make indexable C++ containers behave exactly as one would expect a
              Python container to behave.
            </li>
<li class="listitem">
<p class="simpara">
              Provide default reference semantics for container element indexing
              (<code class="computeroutput"><span class="identifier">__getitem__</span></code>) such
              that c[i] can be mutable. Require:
            </p>
<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>
<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>
<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>
</pre>
<p class="simpara">
              where m is a non-const (mutating) member function (method).
            </p>
</li>
<li class="listitem">
              Return safe references from <code class="computeroutput"><span class="identifier">__getitem__</span></code>
              such that subsequent adds and deletes to and from the container will
              not result in dangling references (will not crash Python).
            </li>
<li class="listitem">
              Support slice indexes.
            </li>
<li class="listitem">
              Accept Python container arguments (e.g. <code class="computeroutput"><span class="identifier">lists</span></code>,
              <code class="computeroutput"><span class="identifier">tuples</span></code>) wherever appropriate.
            </li>
<li class="listitem">
              Allow for extensibility through re-definable policy classes.
            </li>
<li class="listitem">
              Provide predefined support for the most common STL and STL-like indexable
              containers.
            </li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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
        Indexing Interface</a>
</h3></div></div></div>
<p>
          The <code class="computeroutput"><span class="identifier">indexing_suite</span></code> class
          is the base class for the management of C++ containers intended to be integrated
          to Python. The objective is make a C++ container look and feel and behave
          exactly as we'd expect a Python container. The class automatically wraps
          these special Python methods (taken from the Python reference: Emulating
          container types):
        </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">__len__(self)</span></dt>
<dd><p>
                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
                object, an integer <code class="computeroutput"><span class="special">&gt;=</span> <span class="number">0</span></code>. Also, an object that doesn't define
                a <code class="computeroutput"><span class="identifier">__nonzero__</span><span class="special">()</span></code>
                method and whose <code class="computeroutput"><span class="identifier">__len__</span><span class="special">()</span></code> method returns zero is considered
                to be false in a Boolean context.
              </p></dd>
<dt><span class="term">__getitem__(self, key)</span></dt>
<dd><p>
                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
                keys should be integers and slice objects. Note that the special
                interpretation of negative indexes (if the class wishes to emulate
                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
                type, <code class="computeroutput"><span class="identifier">TypeError</span></code> may
                be raised; if of a value outside the set of indexes for the sequence
                (after any special interpretation of negative values), IndexError
                should be raised. [Note: for loops expect that an IndexError will
                be raised for illegal indexes to allow proper detection of the end
                of the sequence.]
              </p></dd>
<dt><span class="term">__setitem__(self, key, value)</span></dt>
<dd><p>
                Called to implement assignment to self[key]. Same note as for __getitem__().
                This should only be implemented for mappings if the objects support
                changes to the values for keys, or if new keys can be added, or for
                sequences if elements can be replaced. The same exceptions should
                be raised for improper key values as for the __getitem__() method.
              </p></dd>
<dt><span class="term">__delitem__(self, key)</span></dt>
<dd><p>
                Called to implement deletion of self[key]. Same note as for __getitem__().
                This should only be implemented for mappings if the objects support
                removal of keys, or for sequences if elements can be removed from
                the sequence. The same exceptions should be raised for improper key
                values as for the __getitem__() method.
              </p></dd>
<dt><span class="term">__iter__(self)</span></dt>
<dd>
<p>
                This method is called when an iterator is required for a container.
                This method should return a new iterator object that can iterate
                over all the objects in the container. For mappings, it should iterate
                over the keys of the container, and should also be made available
                as the method iterkeys().
              </p>
<p>
                Iterator objects also need to implement this method; they are required
                to return themselves. For more information on iterator objects, see
                <a href="https://docs.python.org/3/library/stdtypes.html#iterator-types" target="_top">Iterator
                Types</a> in the <a href="https://docs.python.org/3/library/index.html" target="_top">Python
                Library Reference</a>.
              </p>
</dd>
<dt><span class="term">__contains__(self, item)</span></dt>
<dd><p>
                Called to implement membership test operators. Should return true
                if item is in self, false otherwise. For mapping objects, this should
                consider the keys of the mapping rather than the values or the key-item
                pairs.
              </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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
        sub-classes</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<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>
<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>
</dl></div>
<p>
          The <code class="computeroutput"><span class="identifier">indexing_suite</span></code> is not
          meant to be used as is. A couple of policy functions must be supplied by
          subclasses of <code class="computeroutput"><span class="identifier">indexing_suite</span></code>.
          However, a set of indexing_suite subclasses for the standard indexable
          STL containers will be provided, In most cases, we can simply use the available
          predefined suites. In some cases, we can refine the predefined suites to
          suit our needs.
        </p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<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>
</h4></div></div></div>
<p>
            The <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code>
            class is a predefined <code class="computeroutput"><span class="identifier">indexing_suite</span></code>
            derived class designed to wrap <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
            (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
            all the policies required by the <code class="computeroutput"><span class="identifier">indexing_suite</span></code>.
          </p>
<p>
            Example usage:
          </p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{...};</span>
<span class="special">...</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span> <span class="special">&gt;(</span><span class="string">"XVec"</span><span class="special">)</span>
  <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">vector_indexing_suite</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span> <span class="special">&gt;())</span>
<span class="special">;</span>
</pre>
<p>
            XVec is now a full-fledged Python container (see the example in full,
            along with its python test).
          </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<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>
</h4></div></div></div>
<p>
            The <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code>
            class is a predefined <code class="computeroutput"><span class="identifier">indexing_suite</span></code>
            derived class designed to wrap <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code>
            (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
            all the policies required by the <code class="computeroutput"><span class="identifier">indexing_suite</span></code>.
          </p>
<p>
            Example usage:
          </p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{...};</span>
<span class="special">...</span>

<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span> <span class="special">&gt;(</span><span class="string">"XMap"</span><span class="special">)</span>
    <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">map_indexing_suite</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span> <span class="special">&gt;())</span>
<span class="special">;</span>
</pre>
<p>
            By default indexed elements are returned by proxy. This can be disabled
            by supplying <code class="computeroutput"><span class="keyword">true</span></code> in the
            <code class="computeroutput"><span class="identifier">NoProxy</span></code> template parameter.
            XMap is now a full-fledged Python container (see the example in full,
            along with its python test).
          </p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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>
</h3></div></div></div>
<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>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Template Parameter
                  </p>
                </th>
<th>
                  <p>
                    Requirements
                  </p>
                </th>
<th>
                  <p>
                    Semantics
                  </p>
                </th>
<th>
                  <p>
                    Default
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    Container
                  </p>
                </td>
<td>
                  <p>
                    A class type
                  </p>
                </td>
<td>
                  <p>
                    The container type to be wrapped to Python.
                  </p>
                </td>
<td>
                </td>
</tr>
<tr>
<td>
                  <p>
                    DerivedPolicies
                  </p>
                </td>
<td>
                  <p>
                    A subclass of indexing_suite
                  </p>
                </td>
<td>
                  <p>
                    Derived classes provide the policy hooks. See DerivedPolicies
                    below.
                  </p>
                </td>
<td>
                </td>
</tr>
<tr>
<td>
                  <p>
                    NoProxy
                  </p>
                </td>
<td>
                  <p>
                    A boolean
                  </p>
                </td>
<td>
                  <p>
                    By default indexed elements have Python reference semantics and
                    are returned by proxy. This can be disabled by supplying true
                    in the NoProxy template parameter.
                  </p>
                </td>
<td>
                  <p>
                    false
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    NoSlice
                  </p>
                </td>
<td>
                  <p>
                    A boolean
                  </p>
                </td>
<td>
                  <p>
                    Do not allow slicing.
                  </p>
                </td>
<td>
                  <p>
                    false
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    Data
                  </p>
                </td>
<td>
                </td>
<td>
                  <p>
                    The container's data type.
                  </p>
                </td>
<td>
                  <p>
                    Container::value_type
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    Index
                  </p>
                </td>
<td>
                </td>
<td>
                  <p>
                    The container's index type.
                  </p>
                </td>
<td>
                  <p>
                    Container::size_type
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    Key
                  </p>
                </td>
<td>
                </td>
<td>
                  <p>
                    The container's key type.
                  </p>
                </td>
<td>
                  <p>
                    Container::value_type
                  </p>
                </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span>
	  <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span><span class="special">,</span>
	   <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span>
	   <span class="keyword">bool</span> <span class="identifier">NoSlice</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span>
	   <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>
	   <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>
	   <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">&gt;</span>
<span class="keyword">class</span> <span class="identifier">indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
  <span class="identifier">indexing_suite</span><span class="special">();</span> <span class="comment">// default constructor</span>
<span class="special">}</span>
</pre>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<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>
</h4></div></div></div>
<p>
            Derived classes provide the hooks needed by the indexing_suite:
          </p>
<pre class="programlisting"><span class="identifier">data_type</span><span class="special">&amp;</span>
<span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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="keyword">static</span> <span class="identifier">object</span>
<span class="identifier">get_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>

<span class="keyword">static</span> <span class="keyword">void</span>
<span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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">&amp;</span> <span class="identifier">v</span><span class="special">);</span>

<span class="keyword">static</span> <span class="keyword">void</span>
<span class="identifier">set_slice</span><span class="special">(</span>
    <span class="identifier">Container</span><span class="special">&amp;</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> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span>
<span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iter</span><span class="special">&gt;</span>
<span class="keyword">static</span> <span class="keyword">void</span>
<span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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> <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>

<span class="keyword">static</span> <span class="keyword">void</span>
<span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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="keyword">static</span> <span class="keyword">void</span>
<span class="identifier">delete_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>

<span class="keyword">static</span> <span class="identifier">size_t</span>
<span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="keyword">static</span> <span class="keyword">bool</span>
<span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>

<span class="keyword">static</span> <span class="identifier">index_type</span>
<span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>

<span class="keyword">static</span> <span class="identifier">index_type</span>
<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>
    <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>
</pre>
<p>
            Most of these policies are self explanatory. However, convert_index and
            adjust_index deserve some explanation.
          </p>
<p>
            convert_index converts a Python index into a C++ index that the container
            can handle. For instance, negative indexes in Python, by convention,
            start counting from the right(e.g. C<span class="strikethrough">1</span>
            indexes the rightmost element in C). convert_index should handle the
            necessary conversion for the C++ container (e.g. convert -1 to C.size()-1).
            convert_index should also be able to convert the type of the index (A
            dynamic Python type) to the actual type that the C++ container expects.
          </p>
<p>
            When a container expands or contracts, held indexes to its elements must
            be adjusted to follow the movement of data. For instance, if we erase
            3 elements, starting from index 0 from a 5 element vector, what used
            to be at index 4 will now be at index 1:
          </p>
<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">---&gt;</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="number">4</span>           <span class="number">1</span>
</pre>
<p>
            adjust_index takes care of the adjustment. Given a current index, the
            function should return the adjusted index when data in the container
            at index from..to is replaced by len elements.
          </p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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
        <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a>
</h3></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Template Parameter
                  </p>
                </th>
<th>
                  <p>
                    Requirements
                  </p>
                </th>
<th>
                  <p>
                    Semantics
                  </p>
                </th>
<th>
                  <p>
                    Default
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    Container
                  </p>
                </td>
<td>
                  <p>
                    A class type
                  </p>
                </td>
<td>
                  <p>
                    The container type to be wrapped to Python.
                  </p>
                </td>
<td>
                </td>
</tr>
<tr>
<td>
                  <p>
                    NoProxy
                  </p>
                </td>
<td>
                  <p>
                    A boolean
                  </p>
                </td>
<td>
                  <p>
                    By default indexed elements have Python reference semantics and
                    are returned by proxy. This can be disabled by supplying true
                    in the NoProxy template parameter.
                  </p>
                </td>
<td>
                  <p>
                    false
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    DerivedPolicies
                  </p>
                </td>
<td>
                  <p>
                    A subclass of indexing_suite
                  </p>
                </td>
<td>
                  <p>
                    The vector_indexing_suite may still be derived to further tweak
                    any of the predefined policies. Static polymorphism through CRTP
                    (James Coplien. "Curiously Recurring Template Pattern".
                    C++ Report, Feb. 1995) enables the base indexing_suite class
                    to call policy function of the most derived class
                  </p>
                </td>
<td>
                </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span>
	  <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span>
          <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span> <span class="special">=</span> <span class="identifier">unspecified_default</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">vector_indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified_base</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>

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

    <span class="identifier">data_type</span><span class="special">&amp;</span>
    <span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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="keyword">static</span> <span class="identifier">object</span>
    <span class="identifier">get_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>

    <span class="keyword">static</span> <span class="keyword">void</span>
    <span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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">&amp;</span> <span class="identifier">v</span><span class="special">);</span>

    <span class="keyword">static</span> <span class="keyword">void</span>
    <span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">);</span>

    <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iter</span><span class="special">&gt;</span>
    <span class="keyword">static</span> <span class="keyword">void</span>
    <span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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> <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>

    <span class="keyword">static</span> <span class="keyword">void</span>
    <span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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="keyword">static</span> <span class="keyword">void</span>
    <span class="identifier">delete_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>

    <span class="keyword">static</span> <span class="identifier">size_t</span>
    <span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">);</span>

    <span class="keyword">static</span> <span class="keyword">bool</span>
    <span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">key</span><span class="special">);</span>

    <span class="keyword">static</span> <span class="identifier">index_type</span>
    <span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>

    <span class="keyword">static</span> <span class="identifier">index_type</span>
    <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>
        <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>
<span class="special">};</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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
        <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a>
</h3></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Template Parameter
                  </p>
                </th>
<th>
                  <p>
                    Requirements
                  </p>
                </th>
<th>
                  <p>
                    Semantics
                  </p>
                </th>
<th>
                  <p>
                    Default
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    Container
                  </p>
                </td>
<td>
                  <p>
                    A class type
                  </p>
                </td>
<td>
                  <p>
                    The container type to be wrapped to Python.
                  </p>
                </td>
<td>
                </td>
</tr>
<tr>
<td>
                  <p>
                    NoProxy
                  </p>
                </td>
<td>
                  <p>
                    A boolean
                  </p>
                </td>
<td>
                  <p>
                    By default indexed elements have Python reference semantics and
                    are returned by proxy. This can be disabled by supplying true
                    in the NoProxy template parameter.
                  </p>
                </td>
<td>
                  <p>
                    false
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    DerivedPolicies
                  </p>
                </td>
<td>
                  <p>
                    A subclass of indexing_suite
                  </p>
                </td>
<td>
                  <p>
                    The vector_indexing_suite may still be derived to further tweak
                    any of the predefined policies. Static polymorphism through CRTP
                    (James Coplien. "Curiously Recurring Template Pattern".
                    C++ Report, Feb. 1995) enables the base indexing_suite class
                    to call policy function of the most derived class
                  </p>
                </td>
<td>
                </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span>
          <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span>
          <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span> <span class="special">=</span> <span class="identifier">unspecified_default</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">map_indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified_base</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>

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

    <span class="keyword">static</span> <span class="identifier">data_type</span><span class="special">&amp;</span>
    <span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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="keyword">static</span> <span class="keyword">void</span>
    <span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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">&amp;</span> <span class="identifier">v</span><span class="special">);</span>

    <span class="keyword">static</span> <span class="keyword">void</span>
    <span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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="keyword">static</span> <span class="identifier">size_t</span>
    <span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">);</span>

    <span class="keyword">static</span> <span class="keyword">bool</span>
    <span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">key</span><span class="special">);</span>

    <span class="keyword">static</span> <span class="keyword">bool</span>
    <span class="identifier">compare_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>

    <span class="keyword">static</span> <span class="identifier">index_type</span>
    <span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</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>
<span class="special">};</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2002-2005, 2015 David Abrahams, Stefan Seefeld<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        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>
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>