1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>boost/python/slice.hpp</title> 5<link rel="stylesheet" href="../../boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> 8<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> 9<link rel="prev" href="boost_python_str_hpp.html" title="boost/python/str.hpp"> 10<link rel="next" href="boost_python_tuple_hpp.html" title="boost/python/tuple.hpp"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> 14<hr> 15<div class="spirit-nav"> 16<a accesskey="p" href="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> 17</div> 18<div class="section"> 19<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 20<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> 21</h2></div></div></div> 22<div class="toc"><dl class="toc"> 23<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.introduction">Introduction</a></span></dt> 24<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice">Class 25 <code class="computeroutput"><span class="identifier">slice</span></code></a></span></dt> 26<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_constructors">Class 27 <code class="computeroutput"><span class="identifier">slice</span></code> constructors</a></span></dt> 28<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_observer_functions">Class 29 <code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a></span></dt> 30<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.example">Example</a></span></dt> 31</dl></div> 32<div class="section"> 33<div class="titlepage"><div><div><h3 class="title"> 34<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> 35</h3></div></div></div> 36<p> 37 Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> 38 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. 39 </p> 40</div> 41<div class="section"> 42<div class="titlepage"><div><div><h3 class="title"> 43<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 44 <code class="computeroutput"><span class="identifier">slice</span></code></a> 45</h3></div></div></div> 46<p> 47 Exposes the extended slicing protocol by wrapping the built-in slice type. 48 The semantics of the constructors and member functions defined below can 49 be fully understood by reading the <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> 50 concept definition. Since <code class="computeroutput"><span class="identifier">slice</span></code> 51 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. 52 </p> 53<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> 54<span class="special">{</span> 55 <span class="keyword">class</span> <span class="identifier">slice</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> 56 <span class="special">{</span> 57 <span class="keyword">public</span><span class="special">:</span> 58 <span class="identifier">slice</span><span class="special">();</span> <span class="comment">// create an empty slice, equivalent to [::]</span> 59 60 <span class="keyword">template</span> <span class="special"><</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> 61 <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> 62 63 <span class="keyword">template</span> <span class="special"><</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">></span> 64 <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> 65 66 <span class="comment">// Access the parameters this slice was created with.</span> 67 <span class="identifier">object</span> <span class="identifier">start</span><span class="special">();</span> 68 <span class="identifier">object</span> <span class="identifier">stop</span><span class="special">();</span> 69 <span class="identifier">object</span> <span class="identifier">step</span><span class="special">();</span> 70 71 <span class="comment">// The return type of slice::get_indices()</span> 72 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">></span> 73 <span class="keyword">struct</span> <span class="identifier">range</span> 74 <span class="special">{</span> 75 <span class="identifier">RandomAccessIterator</span> <span class="identifier">start</span><span class="special">;</span> 76 <span class="identifier">RandomAccessIterator</span> <span class="identifier">stop</span><span class="special">;</span> 77 <span class="keyword">int</span> <span class="identifier">step</span><span class="special">;</span> 78 <span class="special">};</span> 79 80 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">></span> 81 <span class="identifier">range</span><span class="special"><</span><span class="identifier">RandomAccessIterator</span><span class="special">></span> 82 <span class="identifier">get_indices</span><span class="special">(</span> 83 <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">begin</span><span class="special">,</span> 84 <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">);</span> 85 <span class="special">};</span> 86<span class="special">}}</span> 87</pre> 88</div> 89<div class="section"> 90<div class="titlepage"><div><div><h3 class="title"> 91<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 92 <code class="computeroutput"><span class="identifier">slice</span></code> constructors</a> 93</h3></div></div></div> 94<pre class="programlisting"><span class="identifier">slice</span><span class="special">();</span></pre> 95<div class="variablelist"> 96<p class="title"><b></b></p> 97<dl class="variablelist"> 98<dt><span class="term">Effects</span></dt> 99<dd><p> 100 constructs a slice with default stop, start, and step values. Equivalent 101 to the slice object created as part of the Python expression <code class="computeroutput"><span class="identifier">base</span><span class="special">[::]</span></code>. 102 </p></dd> 103<dt><span class="term">Throws</span></dt> 104<dd><p> 105 nothing 106 </p></dd> 107</dl> 108</div> 109<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</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> 110<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> 111</pre> 112<div class="variablelist"> 113<p class="title"><b></b></p> 114<dl class="variablelist"> 115<dt><span class="term">Requires</span></dt> 116<dd><p> 117 <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> 118 are of type <code class="computeroutput"><span class="identifier">slice_nil</span></code> 119 or convertible to type <code class="computeroutput"><span class="identifier">object</span></code>. 120 </p></dd> 121<dt><span class="term">Effects</span></dt> 122<dd><p> 123 constructs a new slice with default step value and the provided start 124 and stop values. Equivalent to the slice object created by the built-in 125 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 126 <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>. 127 </p></dd> 128<dt><span class="term">Throws</span></dt> 129<dd><p> 130 <code class="computeroutput"><span class="identifier">error_already_set</span></code> 131 and sets a Python TypeError exception if no conversion is possible 132 from the arguments to type object. 133 </p></dd> 134</dl> 135</div> 136<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</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">></span> 137<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> 138</pre> 139<div class="variablelist"> 140<p class="title"><b></b></p> 141<dl class="variablelist"> 142<dt><span class="term">Requires</span></dt> 143<dd><p> 144 <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> 145 are <code class="computeroutput"><span class="identifier">slice_nil</span></code> or 146 convertible to type <code class="computeroutput"><span class="identifier">object</span></code>. 147 </p></dd> 148<dt><span class="term">Effects</span></dt> 149<dd><p> 150 constructs a new slice with start stop and step values. Equivalent 151 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>, 152 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>. 153 </p></dd> 154<dt><span class="term">Throws</span></dt> 155<dd><p> 156 <code class="computeroutput"><span class="identifier">error_already_set</span></code> 157 and sets a Python TypeError exception if no conversion is possible 158 from the arguments to type object. 159 </p></dd> 160</dl> 161</div> 162</div> 163<div class="section"> 164<div class="titlepage"><div><div><h3 class="title"> 165<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 166 <code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a> 167</h3></div></div></div> 168<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> 169<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> 170<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> 171</pre> 172<div class="variablelist"> 173<p class="title"><b></b></p> 174<dl class="variablelist"> 175<dt><span class="term">Effects</span></dt> 176<dd><p> 177 None 178 </p></dd> 179<dt><span class="term">Throws</span></dt> 180<dd><p> 181 nothing 182 </p></dd> 183<dt><span class="term">Returns</span></dt> 184<dd><p> 185 the parameter that the slice was created with. If the parameter was 186 omitted or <code class="computeroutput"><span class="identifier">slice_nil</span></code> 187 was used when the slice was created, than that parameter will be 188 a reference to <code class="computeroutput"><span class="identifier">PyNone</span></code> 189 and compare equal to a default-constructed object. In principal, 190 any object may be used when creating a slice object, but in practice 191 they are usually integers. 192 </p></dd> 193</dl> 194</div> 195<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">></span> 196<span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span><span class="special"><</span><span class="identifier">RandomAccessIterator</span><span class="special">></span> 197<span class="identifier">slice</span><span class="special">::</span><span class="identifier">get_indices</span><span class="special">(</span> 198 <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">begin</span><span class="special">,</span> 199 <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> 200</pre> 201<div class="variablelist"> 202<p class="title"><b></b></p> 203<dl class="variablelist"> 204<dt><span class="term">Arguments</span></dt> 205<dd><p> 206 A pair of STL-conforming Random Access Iterators that form a half-open 207 range. 208 </p></dd> 209<dt><span class="term">Effects</span></dt> 210<dd><p> 211 Create a RandomAccessIterator pair that defines a fully-closed range 212 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 213 translates this slice's indices while accounting for the effects 214 of any PyNone or negative indices, and non-singular step sizes. 215 </p></dd> 216<dt><span class="term">Returns</span></dt> 217<dd><p> 218 a <code class="computeroutput"><span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span></code> that has been initialized 219 with a non-zero value of step and a pair of RandomAccessIterators 220 that point within the range of this functions arguments and define 221 a closed interval. 222 </p></dd> 223<dt><span class="term">Throws</span></dt> 224<dd><p> 225 Raises a Python TypeError exception if any of this slice's arguments 226 are neither references to PyNone nor convertible to int. Throws 227 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> if the resulting 228 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> 229 within <code class="computeroutput"><span class="keyword">try</span> <span class="special">{</span> 230 <span class="special">...;</span> <span class="special">}</span> 231 <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> 232 <span class="special">{}</span></code> to handle this case and 233 take appropriate action. 234 </p></dd> 235<dt><span class="term">Rationale</span></dt> 236<dd><p> 237 closed-interval: If an open interval were used, then for step size 238 other than 1, the required state for the end iterator would point 239 beyond the one-past-the-end position or before the beginning of the 240 specified range. exceptions on empty slice: It is impossible to define 241 a closed interval over an empty range, so some other form of error 242 checking would have to be used to prevent undefined behavior. In 243 the case where the exception is not caught, it will simply be translated 244 to Python by the default exception handling mechanisms. 245 </p></dd> 246</dl> 247</div> 248</div> 249<div class="section"> 250<div class="titlepage"><div><div><h3 class="title"> 251<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> 252</h3></div></div></div> 253<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> 254 255<span class="comment">// Perform an extended slice of a Python list.</span> 256<span class="comment">// Warning: extended slicing was not supported for built-in types prior </span> 257<span class="comment">// to Python 2.3</span> 258<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> 259<span class="special">{</span> 260 <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> 261<span class="special">}</span> 262 263<span class="comment">// Perform a summation over a slice of a std::vector.</span> 264<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"><</span><span class="keyword">double</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</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> 265<span class="special">{</span> 266 <span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</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="keyword">double</span><span class="special">>::</span><span class="identifier">const_iterator</span><span class="special">></span> <span class="identifier">bounds</span><span class="special">;</span> 267 <span class="keyword">try</span> <span class="special">{</span> 268 <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"><>(</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> 269 <span class="special">}</span> 270 <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> 271 <span class="keyword">return</span> <span class="number">0.0</span><span class="special">;</span> 272 <span class="special">}</span> 273 <span class="keyword">double</span> <span class="identifier">sum</span> <span class="special">=</span> <span class="number">0.0</span><span class="special">;</span> 274 <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> 275 <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> 276 <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> 277 <span class="special">}</span> 278 <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> 279 <span class="keyword">return</span> <span class="identifier">sum</span><span class="special">;</span> 280<span class="special">}</span> 281</pre> 282</div> 283</div> 284<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 285<td align="left"></td> 286<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> 287 Distributed under the Boost Software License, Version 1.0. (See accompanying 288 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> 289 </p> 290</div></td> 291</tr></table> 292<hr> 293<div class="spirit-nav"> 294<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> 295</div> 296</body> 297</html> 298
