boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-21 17:12:22 +00:00
Code Issues Projects Releases Wiki Activity
Files
70d99c5fbb59d9d0b2f32c11fd4049772c135d65
python/doc/html/reference/object_wrappers/boost_python_slice_hpp.html
Travis CI 70d99c5fbb Deploy to GitHub Pages: aaf9022770
2016-11-02 18:30:03 +00:00

306 lines
28 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/slice.hpp</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../index.html" title="Boost.Python Reference Manual">
<link rel="up" href="../object_wrappers.html" title="Chapter&#160;3.&#160;Object Wrappers">
<link rel="prev" href="boost_python_str_hpp.html" title="boost/python/str.hpp">
<link rel="next" href="boost_python_tuple_hpp.html" title="boost/python/tuple.hpp">
</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/bpl.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_str_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_tuple_hpp.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="object_wrappers.boost_python_slice_hpp"></a><a class="link" href="boost_python_slice_hpp.html" title="boost/python/slice.hpp">boost/python/slice.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice">Class
<code class="computeroutput"><span class="identifier">slice</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_constructors">Class
<code class="computeroutput"><span class="identifier">slice</span></code> constructors</a></span></dt>
<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_observer_functions">Class
<code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a></span></dt>
<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="object_wrappers.boost_python_slice_hpp.introduction"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a>
for the Python <a href="http://www.python.org/doc/2.3.3/api/slice-objects.html" target="_top"><code class="computeroutput"><span class="identifier">slice</span></code></a> type.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="object_wrappers.boost_python_slice_hpp.class_slice"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice" title="Class slice">Class
<code class="computeroutput"><span class="identifier">slice</span></code></a>
</h3></div></div></div>
<p>
Exposes the extended slicing protocol by wrapping the built-in slice type.
The semantics of the constructors and member functions defined below can
be fully understood by reading the <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a>
concept definition. Since <code class="computeroutput"><span class="identifier">slice</span></code>
is publicly derived from <a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a>, the public <code class="computeroutput"><span class="identifier">object</span></code> interface applies to <code class="computeroutput"><span class="identifier">slice</span></code> instances as well.
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
<span class="keyword">class</span> <span class="identifier">slice</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">slice</span><span class="special">();</span> <span class="comment">// create an empty slice, equivalent to [::]</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">&gt;</span>
<span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int3</span><span class="special">&gt;</span>
<span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">,</span> <span class="identifier">Int3</span> <span class="identifier">step</span><span class="special">);</span>
<span class="comment">// Access the parameters this slice was created with.</span>
<span class="identifier">object</span> <span class="identifier">start</span><span class="special">();</span>
<span class="identifier">object</span> <span class="identifier">stop</span><span class="special">();</span>
<span class="identifier">object</span> <span class="identifier">step</span><span class="special">();</span>
<span class="comment">// The return type of slice::get_indices()</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">range</span>
<span class="special">{</span>
<span class="identifier">RandomAccessIterator</span> <span class="identifier">start</span><span class="special">;</span>
<span class="identifier">RandomAccessIterator</span> <span class="identifier">stop</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">step</span><span class="special">;</span>
<span class="special">};</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">&gt;</span>
<span class="identifier">range</span><span class="special">&lt;</span><span class="identifier">RandomAccessIterator</span><span class="special">&gt;</span>
<span class="identifier">get_indices</span><span class="special">(</span>
<span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">begin</span><span class="special">,</span>
<span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">end</span><span class="special">);</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="object_wrappers.boost_python_slice_hpp.class_slice_constructors"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_constructors" title="Class slice constructors">Class
<code class="computeroutput"><span class="identifier">slice</span></code> constructors</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">slice</span><span class="special">();</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Effects</span></dt>
<dd><p>
constructs a slice with default stop, start, and step values. Equivalent
to the slice object created as part of the Python expression <code class="computeroutput"><span class="identifier">base</span><span class="special">[::]</span></code>.
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
nothing
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">&gt;</span>
<span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">);</span>
</pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">start</span></code>, <code class="computeroutput"><span class="identifier">stop</span></code>, and <code class="computeroutput"><span class="identifier">step</span></code>
are of type <code class="computeroutput"><span class="identifier">slice_nil</span></code>
or convertible to type <code class="computeroutput"><span class="identifier">object</span></code>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
constructs a new slice with default step value and the provided start
and stop values. Equivalent to the slice object created by the built-in
Python function <code class="computeroutput"><span class="identifier">slice</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span><span class="identifier">stop</span><span class="special">)</span></code>, or as part of the Python expression
<code class="computeroutput"><span class="identifier">base</span><span class="special">[</span><span class="identifier">start</span><span class="special">:</span><span class="identifier">stop</span><span class="special">]</span></code>.
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">error_already_set</span></code>
and sets a Python TypeError exception if no conversion is possible
from the arguments to type object.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int3</span><span class="special">&gt;</span>
<span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">,</span> <span class="identifier">Int3</span> <span class="identifier">step</span><span class="special">);</span>
</pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">start</span></code>, <code class="computeroutput"><span class="identifier">stop</span></code>, and <code class="computeroutput"><span class="identifier">step</span></code>
are <code class="computeroutput"><span class="identifier">slice_nil</span></code> or
convertible to type <code class="computeroutput"><span class="identifier">object</span></code>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
constructs a new slice with start stop and step values. Equivalent
to the slice object created by the built-in Python function <code class="computeroutput"><span class="identifier">slice</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span><span class="identifier">stop</span><span class="special">,</span><span class="identifier">step</span><span class="special">)</span></code>,
or as part of the Python expression <code class="computeroutput"><span class="identifier">base</span><span class="special">[</span><span class="identifier">start</span><span class="special">:</span><span class="identifier">stop</span><span class="special">:</span><span class="identifier">step</span><span class="special">]</span></code>.
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">error_already_set</span></code>
and sets a Python TypeError exception if no conversion is possible
from the arguments to type object.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="object_wrappers.boost_python_slice_hpp.class_slice_observer_functions"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_observer_functions" title="Class slice observer functions">Class
<code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">slice</span><span class="special">::</span><span class="identifier">start</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">object</span> <span class="identifier">slice</span><span class="special">::</span><span class="identifier">stop</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">object</span> <span class="identifier">slice</span><span class="special">::</span><span class="identifier">step</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Effects</span></dt>
<dd><p>
None
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
nothing
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
the parameter that the slice was created with. If the parameter was
omitted or <code class="computeroutput"><span class="identifier">slice_nil</span></code>
was used when the slice was created, than that parameter will be
a reference to <code class="computeroutput"><span class="identifier">PyNone</span></code>
and compare equal to a default-constructed object. In principal,
any object may be used when creating a slice object, but in practice
they are usually integers.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">&gt;</span>
<span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span><span class="special">&lt;</span><span class="identifier">RandomAccessIterator</span><span class="special">&gt;</span>
<span class="identifier">slice</span><span class="special">::</span><span class="identifier">get_indices</span><span class="special">(</span>
<span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">begin</span><span class="special">,</span>
<span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Arguments</span></dt>
<dd><p>
A pair of STL-conforming Random Access Iterators that form a half-open
range.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Create a RandomAccessIterator pair that defines a fully-closed range
within the <code class="computeroutput"><span class="special">[</span><span class="identifier">begin</span><span class="special">,</span><span class="identifier">end</span><span class="special">)</span></code> range of its arguments. This function
translates this slice's indices while accounting for the effects
of any PyNone or negative indices, and non-singular step sizes.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
a <code class="computeroutput"><span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span></code> that has been initialized
with a non-zero value of step and a pair of RandomAccessIterators
that point within the range of this functions arguments and define
a closed interval.
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
Raises a Python TypeError exception if any of this slice's arguments
are neither references to PyNone nor convertible to int. Throws
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> if the resulting
range would be empty. You should always wrap calls to <code class="computeroutput"><span class="identifier">slice</span><span class="special">::</span><span class="identifier">get_indices</span><span class="special">()</span></code>
within <code class="computeroutput"><span class="keyword">try</span> <span class="special">{</span>
<span class="special">...;</span> <span class="special">}</span>
<span class="keyword">catch</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">invalid_argument</span><span class="special">)</span>
<span class="special">{}</span></code> to handle this case and
take appropriate action.
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
closed-interval: If an open interval were used, then for step size
other than 1, the required state for the end iterator would point
beyond the one-past-the-end position or before the beginning of the
specified range. exceptions on empty slice: It is impossible to define
a closed interval over an empty range, so some other form of error
checking would have to be used to prevent undefined behavior. In
the case where the exception is not caught, it will simply be translated
to Python by the default exception handling mechanisms.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="object_wrappers.boost_python_slice_hpp.example"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span>
<span class="comment">// Perform an extended slice of a Python list.</span>
<span class="comment">// Warning: extended slicing was not supported for built-in types prior </span>
<span class="comment">// to Python 2.3</span>
<span class="identifier">list</span> <span class="identifier">odd_elements</span><span class="special">(</span><span class="identifier">list</span> <span class="identifier">l</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">l</span><span class="special">[</span><span class="identifier">slice</span><span class="special">(</span><span class="identifier">_</span><span class="special">,</span><span class="identifier">_</span><span class="special">,</span><span class="number">2</span><span class="special">)];</span>
<span class="special">}</span>
<span class="comment">// Perform a multidimensional extended slice of a Numeric.array</span>
<span class="identifier">numeric</span><span class="special">::</span><span class="identifier">array</span> <span class="identifier">even_columns</span><span class="special">(</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">array</span> <span class="identifier">arr</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// select every other column, starting with the second, of a 2-D array.</span>
<span class="comment">// Equivalent to "return arr[:, 1::2]" in Python.</span>
<span class="keyword">return</span> <span class="identifier">arr</span><span class="special">[</span><span class="identifier">make_tuple</span><span class="special">(</span> <span class="identifier">slice</span><span class="special">(),</span> <span class="identifier">slice</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="identifier">_</span><span class="special">,</span><span class="number">2</span><span class="special">))];</span>
<span class="special">}</span>
<span class="comment">// Perform a summation over a slice of a std::vector.</span>
<span class="keyword">double</span> <span class="identifier">partial_sum</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">Foo</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">slice</span> <span class="identifier">index</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span><span class="special">&gt;</span> <span class="identifier">bounds</span><span class="special">;</span>
<span class="keyword">try</span> <span class="special">{</span>
<span class="identifier">bounds</span> <span class="special">=</span> <span class="identifier">index</span><span class="special">.</span><span class="identifier">get_indices</span><span class="special">&lt;&gt;(</span><span class="identifier">Foo</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">Foo</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span>
<span class="special">}</span>
<span class="keyword">catch</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">invalid_argument</span><span class="special">)</span> <span class="special">{</span>
<span class="keyword">return</span> <span class="number">0.0</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">double</span> <span class="identifier">sum</span> <span class="special">=</span> <span class="number">0.0</span><span class="special">;</span>
<span class="keyword">while</span> <span class="special">(</span><span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span> <span class="special">!=</span> <span class="identifier">bounds</span><span class="special">.</span><span class="identifier">stop</span><span class="special">)</span> <span class="special">{</span>
<span class="identifier">sum</span> <span class="special">+=</span> <span class="special">*</span><span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">advance</span><span class="special">(</span> <span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span><span class="special">,</span> <span class="identifier">bounds</span><span class="special">.</span><span class="identifier">step</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">sum</span> <span class="special">+=</span> <span class="special">*</span><span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">sum</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2002-2005, 2015 David Abrahams, Stefan Seefeld<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_str_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_tuple_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink