833 lines
52 KiB
HTML
833 lines
52 KiB
HTML
<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>
|