boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-27 07:02:15 +00:00
Code Issues Projects Releases Wiki Activity

doc update

Browse Source 
[SVN r15556]
This commit is contained in:
Dave Abrahams
2002-09-29 19:06:13 +00:00
parent a27c2f7a80
commit 0d1efb61e2
7 changed files with 226 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/v2/call_method.html
View File

@@ -85,7 +85,7 @@ R call_method(PyObject* self, char const* method, A1 const&, A2 const&,
<h3>C++ Module Definition</h3>
<pre>
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/utility.hpp&gt;
#include &lt;cstring&gt;

2
doc/v2/copy_const_reference.html
View File

@@ -98,7 +98,7 @@ template &lt;class T&gt; struct apply
<h3>C++ Module Definition</h3>
<pre>
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/copy_const_reference.hpp&gt;
#include &lt;boost/python/return_value_policy.hpp&gt;

2
doc/v2/copy_non_const_reference.html
View File

@@ -99,7 +99,7 @@ template &lt;class T&gt; struct apply
<p>C++ code:</p>
<pre>
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/copy_non_const_reference.hpp&gt;
#include &lt;boost/python/return_value_policy.hpp&gt;

2
doc/v2/data_members.html
View File

@@ -115,7 +115,7 @@ template &lt;class C, class D, class Policies&gt;
member as functions:</p>
<pre>
#include &lt;boost/python/data_members.hpp&gt;
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
struct X

2
doc/v2/has_back_reference.html
View File

@@ -111,7 +111,7 @@ namespace boost { namespace python
<h3>C++ module definition</h3>
<pre>
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/has_back_reference.hpp&gt;
#include &lt;boost/python/handle.hpp&gt;
#include &lt;boost/shared_ptr.hpp&gt;

2
doc/v2/implicit.html
View File

@@ -103,7 +103,7 @@ void implicitly_convertible();
<pre>
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/implicit.hpp&gt;
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
using namespace boost::python;

407
doc/v2/iterator.html
View File

@@ -1,216 +1,239 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<meta name="generator" content="HTML Tidy, see www.w3.org">
<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 - &lt;boost/python/iterator.hpp&gt;</title>
</head>
<body>
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../../index.htm"><img height="86" width="277" alt=
"C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
<h3><a href="../../../../index.htm"><img height="86" width="277"
alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center">Boost.Python</h1>
<h2 align="center">Header &lt;boost/python/iterator.hpp&gt;</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a>
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#classes">Classes</a>
<dt><a href="#classes">Classes</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#iterator-spec">Class template <code>iterator</code></a>
<dt><a href="#iterator-spec">Class template
<code>iterator</code></a></dt>
<dd>
<dl class="page-index">
<dt><a href="#iterator-spec-synopsis">Class
<code>iterator</code> synopsis</a>
<code>iterator</code> synopsis</a></dt>
<dt><a href="#iterator-spec-ctors">Class template <code>iterator</code>
constructor</a>
<dt><a href="#iterator-spec-ctors">Class template
<code>iterator</code> constructor</a></dt>
</dl>
</dl>
</dd>
</dl>
<dl class="page-index">
<dt><a href="#iterators-spec">Class template <code>iterators</code></a>
<dt><a href="#iterators-spec">Class template
<code>iterators</code></a></dt>
<dd>
<dl class="page-index">
<dt><a href="#iterators-spec-synopsis">Class
<code>iterators</code> synopsis</a>
<dt><a href="#iterators-spec-types">Class template
<code>iterators</code> nested types</a>
<dt><a href="#iterators-spec-statics">Class template
<code>iterators</code> static functions</a>
</dl>
</dl>
<code>iterators</code> synopsis</a></dt>
<dt><a href="#functions">Functions</a>
<dt><a href="#iterators-spec-types">Class template
<code>iterators</code> nested types</a></dt>
<dt><a href="#iterators-spec-statics">Class template
<code>iterators</code> static functions</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#functions">Functions</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#range-spec">range</a>
<dt><a href="#range-spec">range</a></dt>
</dl>
</dd>
<dt><a href="#examples">Examples</a>
<dt><a href="#examples">Examples</a></dt>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<p><code>&lt;boost/python/iterator.hpp&gt;</code> provides types
and functions for creating <a
href="http://www.python.org/doc/current/lib/typeiter.html">Python
iterators</a> from <a
href="http://www.sgi.com/tech/stl/Container.html">C++
Containers</a> and <a
<p><code>&lt;boost/python/iterator.hpp&gt;</code> provides types and
functions for creating <a href=
"http://www.python.org/doc/current/lib/typeiter.html">Python
iterators</a> from <a href=
"http://www.sgi.com/tech/stl/Container.html">C++ Containers</a> and <a
href="http://www.sgi.com/tech/stl/Iterators.html">Iterators</a>. Note
that if your <code>class_</code> supports random-access iterators,
implementing
<code><a
href="http://www.python.org/doc/current/ref/sequence-types.html#l2h-128">__getitem__</a></code>
(also known as the Sequence Protocol) may serve you better than
using this facility: Python will automatically create an iterator
type for you (see <a
href="http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35">iter()</a>),
and each access can be range-checked, leaving no possiblity of
accessing through an invalidated C++ iterator.
implementing <code><a href=
"http://www.python.org/doc/current/ref/sequence-types.html#l2h-128">__getitem__</a></code>
(also known as the Sequence Protocol) may serve you better than using
this facility: Python will automatically create an iterator type for you
(see <a href=
"http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35">iter()</a>),
and each access can be range-checked, leaving no possiblity of accessing
through an invalidated C++ iterator.</p>
<h2><a name="classes"></a>Classes</h2>
<h3><a name="iterator-spec"></a>Class Template <code>iterator</code></h3>
<p>Instances of <code>iterator&lt;C,P&gt;</code> hold a reference
to a callable Python object which, when invoked from Python,
expects a single argument <code>c</code> convertible to
<code>C</code> and creates a Python iterator that traverses
[<code>c.begin()</code>,
<code>c.end()</code>). The optional <a
href="CallPolicies.html">CallPolicies</a>
<code>P</code> can be used to control how elements are returned
during iteration.
<p>Instances of <code>iterator&lt;C,P&gt;</code> hold a reference to a
callable Python object which, when invoked from Python, expects a single
argument <code>c</code> convertible to <code>C</code> and creates a
Python iterator that traverses [<code>c.begin()</code>,
<code>c.end()</code>). The optional <a href=
"CallPolicies.html">CallPolicies</a> <code>P</code> can be used to
control how elements are returned during iteration.</p>
<p>In the table below, <code><b>c</b></code> is an instance of <code>Container</code>.
<p>In the table below, <code><b>c</b></code> is an instance of
<code>Container</code>.</p>
<table border="1" summary="iterator template parameters">
<tr>
<th>Template Parameter
<th>Template Parameter</th>
<th>Requirements
<th>Requirements</th>
<th>Semantics
<th>Semantics</th>
<th>Default
<th>Default</th>
</tr>
<tr>
<td><code>Container</code>
<td><code>Container</code></td>
<td>[c.begin(),c.end()) is a valid <a
href="http://www.sgi.com/tech/stl/Iterators.html">Iterator
range</a>.
<td>The result will convert its argument to
<code>c</code> and call
<code>c.begin()</code> and <code>c.end()</code> to acquire
iterators. To invoke <code>Container</code>'s
<code>const</code> <code>begin()</code> and <code>end()</code>
functions, make it <code>const</code>.
<td>[c.begin(),c.end()) is a valid <a href=
"http://www.sgi.com/tech/stl/Iterators.html">Iterator range</a>.</td>
<td>The result will convert its argument to <code>c</code> and call
<code>c.begin()</code> and <code>c.end()</code> to acquire iterators.
To invoke <code>Container</code>'s <code>const</code>
<code>begin()</code> and <code>end()</code> functions, make it
<code>const</code>.</td>
</tr>
<tr>
<td><code>NextPolicies</code>
<td><code>NextPolicies</code></td>
<td>A default-constructible model of <a
href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>.
<td>A default-constructible model of <a href=
"CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</td>
<td>Applied to the resulting iterators' <code>next()</code> method.
<td>An unspecified model of <a
href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>
which always makes a copy of the
result of deferencing the underlying C++ iterator
<td>Applied to the resulting iterators' <code>next()</code>
method.</td>
<td>An unspecified model of <a href=
"CallPolicies.html#CallPolicies-concept">CallPolicies</a> which
always makes a copy of the result of deferencing the underlying C++
iterator</td>
</tr>
</table>
<h4><a name="iterator-spec-synopsis"></a>Class Template iterator synopsis</h4>
<h4><a name="iterator-spec-synopsis"></a>Class Template iterator
synopsis</h4>
<pre>
namespace boost { namespace python
{
template &lt;class Container
, class NextPolicies = <i>unspecified</i>&gt;
struct iterator : reference&lt;PyObject*&gt;
struct iterator : <a href="object.html#object-spec">object</a>
{
iterator();
};
}}
</pre>
<h4><a name="iterator-spec-constructors"></a>Class Template
iterator constructor</h4>
<h4><a name="iterator-spec-constructors"></a>Class Template iterator
constructor</h4>
<pre>
iterator()
</pre>
<dl class="function-semantics">
<dt><b>Effects:</b> Initializes its base class with the result
of:
<dt><b>Effects:</b></dt>
<dd>
Initializes its base class with the result of:
<pre>
range&lt;NextPolicies&gt;(&amp;iterators&lt;Container&gt;::begin, &amp;iterators&lt;Container&gt;::end)
</pre>
</dd>
<dt><b>Postconditions:</b> <code>this-&gt;get()</code> points to
a Python callable object which creates a Python iterator as
described above.
<dt><b>Postconditions:</b> <code>this-&gt;get()</code> points to a
Python callable object which creates a Python iterator as described
above.</dt>
<dt><b>Rationale:</b> Provides an easy way to create iterators
for the common case where a C++ class being wrapped provides
<code>begin()</code> and <code>end()</code>.
<dt><b>Rationale:</b> Provides an easy way to create iterators for the
common case where a C++ class being wrapped provides
<code>begin()</code> and <code>end()</code>.</dt>
</dl>
<!-- -->
<!-- -->
<h3><a name="iterators-spec"></a>Class Template
<code>iterators</code></h3>
<h3><a name="iterators-spec"></a>Class Template <code>iterators</code></h3>
<p>A utility class template which provides a way to reliably call its
argument's <code>begin()</code> and <code>end()</code> member functions.
Note that there is no portable way to take the address of a member
function of a C++ standard library container, so
<code>iterators&lt;&gt;</code> can be particularly helpful when wrapping
them.</p>
<p>A utility class template which provides a way to reliably call
its argument's <code>begin()</code> and <code>end()</code> member
functions. Note that there is no portable way to take the address
of a member function of a C++ standard library container, so
<code>iterators&lt;&gt;</code> can be particularly helpful when
wrapping them.
<p>In the table below, <code><b>x</b></code> is an instance of <code>C</code>.
<p>In the table below, <code><b>x</b></code> is an instance of
<code>C</code>.</p>
<table border="1" summary="iterator template parameters">
<tr>
<th>Required Valid Expression
<th>Required Valid Expression</th>
<th>Type
<th>Type</th>
</tr>
<tr>
<td><code>x.begin()</code>
<td>Convertible to <code>C::const_iterator</code> if <code>C</code> is a
<code>const</code> type; convertible to <code>C::iterator</code> otherwise.
<td><code>x.begin()</code></td>
<td>Convertible to <code>C::const_iterator</code> if <code>C</code>
is a <code>const</code> type; convertible to <code>C::iterator</code>
otherwise.</td>
</tr>
<tr>
<td><code>x.end()</code>
<td>Convertible to <code>C::const_iterator</code> if <code>C</code> is a
<code>const</code> type; convertible to <code>C::iterator</code> otherwise.
<td><code>x.end()</code></td>
<td>Convertible to <code>C::const_iterator</code> if <code>C</code>
is a <code>const</code> type; convertible to <code>C::iterator</code>
otherwise.</td>
</tr>
</table>
<h4><a name="iterators-spec-synopsis"></a>Class Template iterators synopsis</h4>
<h4><a name="iterators-spec-synopsis"></a>Class Template iterators
synopsis</h4>
<pre>
namespace boost { namespace python
{
@@ -224,141 +247,151 @@ namespace boost { namespace python
}}
</pre>
<h4><a name="iterators-spec-types"></a>Class Template
iterators nested types</h4>
If C is a <code>const</code> type,
<h4><a name="iterators-spec-types"></a>Class Template iterators nested
types</h4>
If C is a <code>const</code> type,
<pre>
typedef typename C::const_iterator iterator;
</pre>
Otherwise:
Otherwise:
<pre>
typedef typename C::iterator iterator;
</pre>
<h4><a name="iterators-spec-statics"></a>Class Template
iterators static functions</h4>
<h4><a name="iterators-spec-statics"></a>Class Template iterators static
functions</h4>
<pre>
static iterator begin(C&amp;);
</pre>
<dl class="function-semantics">
<dt><b>Returns:</b> <code>x.begin()</code>
<dt><b>Returns:</b> <code>x.begin()</code></dt>
</dl>
<pre>
static iterator end(C&amp;);
</pre>
<dl class="function-semantics">
<dt><b>Returns:</b> <code>x.end()</code>
<dt><b>Returns:</b> <code>x.end()</code></dt>
</dl>
<!-- -->
<!-- -->
<h2><a name="functions"></a>Functions</h2>
<pre>
<a name=
"range-spec">template</a> &lt;class NextPolicies, class Target, class Accessor1, class Accessor2&gt;
reference&lt;PyObject*&gt range(Accessor1 start, Accessor2 finish);
<a href=
"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish);
template &lt;class NextPolicies, class Accessor1, class Accessor2&gt;
reference&lt;PyObject*&gt range(Accessor1 start, Accessor2 finish);
<a href=
"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish);
template &lt;class Accessor1, class Accessor2&gt;
reference&lt;PyObject*&gt range(Accessor1 start, Accessor2 finish);
<a href=
"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish);
</pre>
<dl class="range-semantics">
<dt><b>Requires:</b> <code>NextPolicies</code> is a
default-constructible model of <a
href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>.
default-constructible model of <a href=
"CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</dt>
<dt><b>Effects:</b> <dl>
<dt><b>Effects:</b></dt>
The first form creates a Python callable
object which, when invoked, converts its argument to a
<code>Target</code> object
<code>x</code>, and creates a Python iterator which traverses
[<code><a
href="../../../bind/bind.html">bind</a>(start,_1)(x)</code>,&nbsp;<code><a
href="../../../bind/bind.html">bind</a>(finish,_1)(x)</code>),
applying <code>NextPolicies</code> to the iterator's
<code>next()</code> function.
<dd>
<dt>The second form is identical to
the first, except that <code>Target</code> is deduced from
<code>Accessor1</code> as follows:
<ol>
<li>If <code>Accessor1</code> is a function type,
<code>Target</code> is the type of its first argument.
<li>If <code>Accessor1</code> is a data member pointer of the
form <code>R&nbsp;(T::*)</code>, <code>Target</code> is
identical to <code>T</code>.
<li>If <code>Accessor1</code> is a member function pointer of
the form
<code>R&nbsp;(T::*)(</code><i>arguments...</i><code>)</code>&nbsp;<i>cv-opt</i>,
where <i>cv-opt</i> is an optional <code>cv-qualifier</code>,
<code>Target</code> is identical to <code>T</code>.
</ol>
<dd>
<dd>
<dl>
<dt>The first form creates a Python callable object which, when
invoked, converts its argument to a <code>Target</code> object
<code>x</code>, and creates a Python iterator which traverses
[<code><a href=
"../../../bind/bind.html">bind</a>(start,_1)(x)</code>,&nbsp;<code><a
href="../../../bind/bind.html">bind</a>(finish,_1)(x)</code>),
applying <code>NextPolicies</code> to the iterator's
<code>next()</code> function.</dt>
<dt>The third form is identical to the second, except that
<code>NextPolicies</code> is an unspecified model of <a
href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>
which always makes a copy of the
result of deferencing the underlying C++ iterator<dd>
</dl>
<dt>The second form is identical to the first, except that
<code>Target</code> is deduced from <code>Accessor1</code> as
follows:</dt>
<dd>
<ol>
<li>If <code>Accessor1</code> is a function type,
<code>Target</code> is the type of its first argument.</li>
<dt><b>Rationale:</b> The use of <code><a
href="../../../bind/bind.html">boost::bind</a>()</code> allows
C++ iterators to be accessed through functions, member functions
or data member pointers. Customization of
<code>NextPolicies</code> (e.g. using <code><a
href="return_internal_reference.html#return_internal_reference-spec"
>return_internal_reference</a></code>) is useful when it is
expensive to copy sequence elements of a wrapped class
type. Customization of <code>Target</code> is useful when
<code>Accessor1</code> is a function object, or when a base
class of the intended target type would otherwise be deduced.
<li>If <code>Accessor1</code> is a data member pointer of the
form <code>R&nbsp;(T::*)</code>, <code>Target</code> is
identical to <code>T</code>.</li>
<li>If <code>Accessor1</code> is a member function pointer of
the form
<code>R&nbsp;(T::*)(</code><i>arguments...</i><code>)</code>&nbsp;
<i>cv-opt</i>, where <i>cv-opt</i> is an optional
<code>cv-qualifier</code>, <code>Target</code> is identical to
<code>T</code>.</li>
</ol>
</dd>
<dt>The third form is identical to the second, except that
<code>NextPolicies</code> is an unspecified model of <a href=
"CallPolicies.html#CallPolicies-concept">CallPolicies</a> which
always makes a copy of the result of deferencing the underlying C++
iterator</dt>
</dl>
</dd>
<dt><b>Rationale:</b> The use of <code><a href=
"../../../bind/bind.html">boost::bind</a>()</code> allows C++ iterators
to be accessed through functions, member functions or data member
pointers. Customization of <code>NextPolicies</code> (e.g. using
<code><a href=
"return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code>)
is useful when it is expensive to copy sequence elements of a wrapped
class type. Customization of <code>Target</code> is useful when
<code>Accessor1</code> is a function object, or when a base class of
the intended target type would otherwise be deduced.</dt>
</dl>
<h2><a name="examples"></a>Examples</h2>
<pre>
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/return_internal_reference.hpp&gt;
#include &lt;vector&gt;
using namespace boost::python;
BOOST_PYTHON_MODULE_INIT(demo)
{
module(&quot;demo&quot;)
.add(
class_&lt;std::vector&lt;double&gt; &gt;(&quot;dvec&quot;)
.def(&quot;__iter__&quot;, iterator&lt;std::vector&lt;double&gt; &gt;())
...
)
;
class_&lt;std::vector&lt;double&gt; &gt;("dvec")
.def("__iter__", iterator&lt;std::vector&lt;double&gt; &gt;())
;
}
</pre>
A more comprehensive example can be found in:
A more comprehensive example can be found in:
<code><dl>
<dt><a href="../../test/iterator.cpp">libs/python/test/iterator.cpp</a><dd>
<dt><a href="../../test/input_iterator.cpp">libs/python/test/input_iterator.cpp</a><dd>
<dt><a href="../../test/iterator.py">libs/python/test/input_iterator.py</a><dd>
</code>
<dl>
<dt><code><a href=
"../../test/iterator.cpp">libs/python/test/iterator.cpp</a></code></dt>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
17 May, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
<dt><code><a href=
"../../test/input_iterator.cpp">libs/python/test/input_iterator.cpp</a></code></dt>
<dt><code><a href=
"../../test/iterator.py">libs/python/test/input_iterator.py</a></code></dt>
<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
Abrahams</a> 2002. All Rights Reserved.</i>
<dd>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
29 September, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All
Rights Reserved.</i></p>
</dd>
</dl>
</body>
</html>