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 8. Topics">
- <link rel="prev" href="pickle_support.html" title="Pickle support">
- <link rel="next" href="../glossary.html" title="Chapter 9. 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">>=</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"><</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>
- <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>
- <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"><</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>
- <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>
- <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"><</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">></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">&</span>
- <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>
- <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">&</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">&</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>
- <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">&</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">&</span> <span class="identifier">v</span>
- <span class="special">);</span>
- <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Iter</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">&</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">&</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">&</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">&</span> <span class="identifier">container</span><span class="special">);</span>
- <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</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">&</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>
- <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">&</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">---></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"><</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">></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">&</span>
- <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>
- <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">&</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">&</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>
- <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">&</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">&</span> <span class="identifier">v</span><span class="special">);</span>
- <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Iter</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">&</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">&</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">&</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">&</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">&</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>
- <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">&</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"><</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">></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">&</span>
- <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>
- <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">&</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>
- <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">&</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">&</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">&</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>
- <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">&</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">&</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 © 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>
|