diff options
Diffstat (limited to 'libs/python/doc/v2/slice.html')
| -rw-r--r-- | libs/python/doc/v2/slice.html | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/libs/python/doc/v2/slice.html b/libs/python/doc/v2/slice.html new file mode 100644 index 000000000..fb6b47c7e --- /dev/null +++ b/libs/python/doc/v2/slice.html @@ -0,0 +1,246 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> +<head> + <meta name="generator" + content="HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> + <meta http-equiv="Content-Type" + content="text/html; charset=iso-8859-1"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + <title>Boost.Python - <boost/python/slice.hpp></title> +</head> +<body> +<table border="0" cellpadding="7" cellspacing="0" width="100%" + summary="header"> + <tbody> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../../index.htm"><img height="86" width="277" + alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Header <boost/python/slice.hpp></h2> + </td> + </tr> + </tbody> +</table> +<hr> +<h2>Contents</h2> +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#classes">Classes</a></dt> + <dd> + <dl class="page-index"> + <dt><a href="#slice-spec">Class <code>slice</code></a></dt> + <dd> + <dl class="page-index"> + <dt><a href="#slice-spec-synopsis">Class <code>slice</code> +synopsis</a></dt> + <dt><a href="#slice-spec-ctors">Class <code>slice</code> +constructors</a></dt> + <dt><a href="#slice-spec-observers">Class <code>slice</code> +observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + <dt><a href="#examples">Example(s)</a></dt> +</dl> +<hr> +<h2><a name="introduction"></a>Introduction</h2> +<p>Exposes a <a href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> +for the Python <a + href="http://www.python.org/doc/2.3.3/api/slice-objects.html">slice</a> +type.</p> +<h2><a name="classes"></a>Classes</h2> +<h3><a name="slice-spec"></a>Class <code>slice</code></h3> +<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 + href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept +definition. Since <code>slice</code> is publicly derived from <code><a + href="object.html#object-spec">object</a></code>, the public object +interface applies to <code>slice</code> instances as well.<br> +</p> +<h4><a name="slice-spec-synopsis"></a>Class <code>slice</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + class slice : public object + { + public: + slice(); // create an empty slice, equivalent to [::] + + template <typename Int1, typename Int2> + slice(Int1 start, Int2 stop); + + template <typename Int1, typename Int2, typename Int3> + slice(Int1 start, Int2 stop, Int3 step); + + // Access the parameters this slice was created with. + object start(); + object stop(); + object step(); + + // The return type of slice::get_indices() + template <typename RandomAccessIterator> + struct range + { + RandomAccessIterator start; + RandomAccessIterator stop; + int step; + }; + + template <typename RandomAccessIterator> + range<RandomAccessIterator> + get_indices( + RandomAccessIterator const& begin, + RandomAccessIterator const& end); + }; +}} +</pre> +<h4><a name="slice-spec-ctors"></a>Class <code>slice</code> +constructors<br> +</h4> +<pre>slice();<br></pre> +<dl class="function-semantics"> + <dt><b>Effects:</b> constructs a <code>slice</code> with default stop, start, and +step values. Equivalent to the slice object created as part of the Python +expression <code>base[::].</code></dt> + <dt><b>Throws:</b> nothing.</dt> +</dl> +<pre> +template <typename Int1, typename Int2> +slice(Int1 start, Int2 stop); +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> <code>start</code>, <code>stop</code>, and <code>step</code> + are of type <code><a href="object.html#slice_nil-spec">slice_nil</a></code> + or convertible to type <code>object</code>.</dt> + <dt><b>Effects:</b> 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><a + href="http://www.python.org/doc/current/lib/built-in-funcs.html#12h-62">slice(start,stop)</a></code>, +or as part of the Python expression <code>base[start:stop]</code>.</dt> + <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python <code>TypeError</code> +exception if no conversion is possible from the arguments to type <code>object</code>.</dt> +</dl> +<pre> +template <typename Int1, typename Int2, typename Int3> +slice(Int1 start, Int2 stop, Int3 step); +</pre> + <dt><b>Requires:</b> <code>start</code>, <code>stop</code>, and <code>step</code> are <code>slice_nil</code> or convertible to type <code>object</code>.</dt> + <dt><b>Effects:</b> constructs a new slice with start stop and step +values. Equivalent to the slice object created +by the built-in Python function <code><a + href="http://www.python.org/doc/current/lib/built-in-funcs.html">slice(start,stop,step)</a></code>, +or as part of the Python expression <code>base[start:stop:step]</code>.</dt> + <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python <code>TypeError</code> +exception if no conversion is possible from the arguments to type +object.</dt> +<h4><a name="slice-spec-observers"></a>Class <code>slice</code> +observer functions<br> +</h4> +<pre> +object slice::start() const; +object slice::stop() const; +object slice::step() const; +</pre> +<dl class="function-semantics"> + <dt><b>Effects:</b> None.</dt> + <dt><b>Throws:</b> nothing.</dt> + <dt><b>Returns:</b>the parameter that +the slice was created with. If the parameter was omitted or +slice_nil was used when the slice was created, than that parameter will +be a reference to PyNone 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.</dt> +</dl> +<br> +<pre> +template <typename RandomAccessIterator> +slice::range<RandomAccessIterator> +slice::get_indices( + RandomAccessIterator const& begin, + RandomAccessIterator const& end) const; +</pre> +<dl class="function-semantics"> + <dt><b>Arguments:</b> A pair of STL-conforming Random Access +Iterators that form a half-open range.</dt> + <dt><b>Effects:</b> Create a RandomAccessIterator pair that defines a +fully-closed range within the [begin,end) 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.</dt> + <dt><b>Returns:</b> a slice::range +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.</dt> + <dt><b>Throws:</b> <a href="definitions.html#raise">Raises</a> a Python <code>TypeError</code> exception if any of this slice's arguments +are neither references to <code>PyNone</code> nor convertible to <code>int</code>. Throws +<code>std::invalid_argument</code> if the resulting range would be empty. You +should always wrap calls to <code>slice::get_indices()</code> +within <code>try { ...; } catch (std::invalid_argument) {}</code> to +handle this case and take appropriate action.</dt> + <dt><b>Rationale</b>: 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.<br> +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. </dt> +</dl> +<h2><a name="examples"></a><b>Examples</b></h2> +<pre> +using namespace boost::python; + +// Perform an extended slice of a Python list. +// Warning: extended slicing was not supported for built-in types prior +// to Python 2.3 +list odd_elements(list l) +{ + return l[slice(_,_,2)]; +} + +// Perform a multidimensional extended slice of a Numeric.array +numeric::array even_columns(numeric::array arr) +{ + // select every other column, starting with the second, of a 2-D array. + // Equivalent to "return arr[:, 1::2]" in Python. + return arr[make_tuple( slice(), slice(1,_,2))]; +} + +// Perform a summation over a slice of a std::vector. +double partial_sum(std::vector<double> const& Foo, const slice index) +{ + slice::range<std::vector<double>::const_iterator> bounds; + try { + bounds = index.get_indices<>(Foo.begin(), Foo.end()); + } + catch (std::invalid_argument) { + return 0.0; + } + double sum = 0.0; + while (bounds.start != bounds.stop) { + sum += *bounds.start; + std::advance( bounds.start, bounds.step); + } + sum += *bounds.start; + return sum; +} +</pre> +<p>Revised 07 Febuary, 2004</p> +<p><i>© Copyright <a + href="mailto:jbrandmeyer@users.sourceforge.net">Jonathan Brandmeyer</a>, +2004. Modification, copying and redistribution of this document +is permitted under the terms and conditions of the Boost Software +License, version 1.0.<br> +</i></p> +</body> +</html> |