[DEV] add v1.66.0

This commit is contained in:
2018-01-12 21:47:58 +01:00
parent 87059bb1af
commit a97e9ae7d4
49032 changed files with 7668950 additions and 0 deletions

View File

@@ -0,0 +1,220 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/def.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="next" href="boost_python_def_visitor_hpp.html" title="boost/python/def_visitor.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../high_level_components.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_def_visitor_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="high_level_components.boost_python_def_hpp"></a><a class="link" href="boost_python_def_hpp.html" title="boost/python/def.hpp">boost/python/def.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions">Functions</a></span></dt>
<dt><span class="section"><a href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_def_hpp.introduction"></a><a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">def</span><span class="special">()</span></code>
is the function which can be used to expose C++ functions and callable
objects as Python functions in the <a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">current
scope</a>.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_def_hpp.functions"></a><a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions" title="Functions">Functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&amp;);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&amp;);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">A3</span> <span class="keyword">const</span><span class="special">&amp;);</span>
</pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd>
<p>
name is an <a class="link" href="../glossary.html#ntbs">ntbs</a> which conforms to Python's
<a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier
naming rules</a>.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
If <code class="computeroutput"><span class="identifier">Fn</span></code> is [derived
from] <a class="link" href="../object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object">object</a>,
it will be added to the <a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">current
scope</a> as a single overload. To be useful, <code class="computeroutput"><span class="identifier">fn</span></code> should be <a href="http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6" target="_top">callable</a>.
</li>
<li class="listitem">
<p class="simpara">
If <code class="computeroutput"><span class="identifier">a1</span></code> is the
result of an <a class="link" href="../function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">overload-dispatch-expression</a>,
only the second form is allowed and <code class="computeroutput"><span class="identifier">fn</span></code>
must be a pointer to function or pointer to member function whose
<a class="link" href="../glossary.html#arity">arity</a> is the same as A1's <a class="link" href="../function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">maximum
arity</a>.
</p>
<p class="simpara">
<span class="bold"><strong>Effects:</strong></span> For each prefix <code class="computeroutput"><span class="identifier">P</span></code> of <code class="computeroutput"><span class="identifier">Fn</span></code>'s
sequence of argument types, beginning with the one whose length
is <code class="computeroutput"><span class="identifier">A1</span></code>'s <a class="link" href="../function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">minimum
arity</a>, adds a <code class="computeroutput"><span class="identifier">name</span><span class="special">(...)</span></code> function overload to the
<a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">current
scope</a>. Each overload generated invokes a1's call-expression
with P, using a copy of a1's call policies. If the longest valid
prefix of A1 contains N types and a1 holds M keywords, an initial
sequence of the keywords are used for all but the first N - M
arguments of each overload.
</p>
</li>
<li class="listitem">
<p class="simpara">
Otherwise, fn must be a non-null function or member function
pointer, and a single function overload built around fn is added
to the current scope. If any of a1-a3 are supplied, they may
be selected in any order from the table below.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Mnemonic Name
</p>
</th>
<th>
<p>
Requirements/Type properties
</p>
</th>
<th>
<p>
Effects
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
docstring
</p>
</td>
<td>
<p>
Any <a class="link" href="../glossary.html#ntbs">ntbs</a>
</p>
</td>
<td>
<p>
Value will be bound to the <code class="computeroutput"><span class="identifier">__doc__</span></code>
attribute of the resulting method overload.
</p>
</td>
</tr>
<tr>
<td>
<p>
policies
</p>
</td>
<td>
<p>
A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>
</p>
</td>
<td>
<p>
A copy will be used as the call policies of the resulting
method overload.
</p>
</td>
</tr>
<tr>
<td>
<p>
keywords
</p>
</td>
<td>
<p>
The result of a <a class="link" href="../function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expression</a>
specifying no more arguments than the <a class="link" href="../glossary.html#arity">arity</a>
of <code class="computeroutput"><span class="identifier">fn</span></code>.
</p>
</td>
<td>
<p>
A copy will be used as the call policies of the resulting
method overload.
</p>
</td>
</tr>
</tbody>
</table></div>
</li>
</ul></div>
</dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_def_hpp.example"></a><a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<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="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span> <span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">def_test</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">),</span> <span class="string">"foo's docstring"</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="../high_level_components.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_def_visitor_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,208 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/def_visitor.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_def_hpp.html" title="boost/python/def.hpp">
<link rel="next" href="boost_python_docstring_options_h.html" title="boost/python/docstring_options.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_def_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_docstring_options_h.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="high_level_components.boost_python_def_visitor_hpp"></a><a class="link" href="boost_python_def_visitor_hpp.html" title="boost/python/def_visitor.hpp">boost/python/def_visitor.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.class_def_visitor">Class
<code class="computeroutput"><span class="identifier">def_visitor</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_def_visitor_hpp.introduction"></a><a class="link" href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
&lt;boost/python/def_visitor.hpp&gt; provides a generic visitation interface
through which the <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_&lt;T, Bases, HeldType, NonCopyable&gt;">class_</a>
def member functionality can be extended non-intrusively to avoid cluttering
the <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_&lt;T, Bases, HeldType, NonCopyable&gt;">class_</a>
interface. It declares the <code class="computeroutput"><span class="identifier">def_visitor</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> class template, which is parameterized
on the derived type <code class="computeroutput"><span class="identifier">DerivedVisitor</span></code>,
which provides the actual <code class="computeroutput"><span class="identifier">def</span></code>
functionality through its <code class="computeroutput"><span class="identifier">visit</span></code>
member functions.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_def_visitor_hpp.class_def_visitor"></a><a class="link" href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.class_def_visitor" title="Class def_visitor">Class
<code class="computeroutput"><span class="identifier">def_visitor</span></code></a>
</h3></div></div></div>
<p>
The class <code class="computeroutput"><span class="identifier">def_visitor</span></code> is
a base class paramaterized by its derived class. The <code class="computeroutput"><span class="identifier">def_visitor</span></code>
class is a protocol class. Its derived class, DerivedVisitor, is expected
to have a member function <code class="computeroutput"><span class="identifier">visit</span></code>.
The <code class="computeroutput"><span class="identifier">def_visitor</span></code> class is
never instantiated directly. Instead, an instance of its subclass, DerivedVisitor,
is passed on as an argument to the <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_&lt;T, Bases, HeldType, NonCopyable&gt;">class_</a>
<code class="computeroutput"><span class="identifier">def</span></code> member function.
</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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">DerivedVisitor</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">def_visitor</span> <span class="special">{};</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>
The client supplied class DerivedVisitor template parameter is expected
to: * be privately derived from def_visitor * grant friend access
to class def_visitor_access * define either or both visit member
functions listed in the table below:
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Requirements
</p>
</th>
<th>
<p>
Effects
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">visitor</span><span class="special">.</span><span class="identifier">visit</span><span class="special">(</span><span class="identifier">cls</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">void</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">cls</span></code> is
an instance of a <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_&lt;T, Bases, HeldType, NonCopyable&gt;">class_</a>
being wrapped to Python. <code class="computeroutput"><span class="identifier">visitor</span></code>
is a <code class="computeroutput"><span class="identifier">def_visitor</span></code>
derived class.
</p>
</td>
<td>
<p>
A call to <code class="computeroutput"><span class="identifier">cls</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">visitor</span><span class="special">)</span></code> forwards to this member
function.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">visitor</span><span class="special">.</span><span class="identifier">visit</span><span class="special">(</span><span class="identifier">cls</span><span class="special">,</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">options</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">void</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">cls</span></code> is
a <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_&lt;T, Bases, HeldType, NonCopyable&gt;">class_</a>
instance, name is a C string. <code class="computeroutput"><span class="identifier">visitor</span></code>
is a <code class="computeroutput"><span class="identifier">def_visitor</span></code>
derived class. options is a context specific optional argument.
</p>
</td>
<td>
<p>
A call to <code class="computeroutput"><span class="identifier">cls</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">visitor</span><span class="special">)</span></code> or <code class="computeroutput"><span class="identifier">cls</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">visitor</span><span class="special">,</span> <span class="identifier">options</span><span class="special">)</span></code> forwards to this member
function.
</p>
</td>
</tr>
</tbody>
</table></div>
</dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_def_visitor_hpp.example"></a><a class="link" href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{/*...*/};</span>
<span class="keyword">class</span> <span class="identifier">my_def_visitor</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">def_visitor</span><span class="special">&lt;</span><span class="identifier">my_def_visitor</span><span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">friend</span> <span class="keyword">class</span> <span class="identifier">def_visitor_access</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">classT</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">visit</span><span class="special">(</span><span class="identifier">classT</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">)</span> <span class="keyword">const</span>
<span class="special">{</span>
<span class="identifier">c</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">my_def_visitor</span><span class="special">::</span><span class="identifier">foo</span><span class="special">);</span>
<span class="identifier">c</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">my_def_visitor</span><span class="special">::</span><span class="identifier">bar</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">X</span><span class="special">&amp;</span> <span class="identifier">self</span><span class="special">);</span>
<span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">bar</span><span class="special">(</span><span class="identifier">X</span><span class="special">&amp;</span> <span class="identifier">self</span><span class="special">);</span>
<span class="special">};</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_ext</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;(</span><span class="string">"X"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">my_def_visitor</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_def_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_docstring_options_h.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,363 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/docstring_options.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_def_visitor_hpp.html" title="boost/python/def_visitor.hpp">
<link rel="next" href="boost_python_enum_hpp.html" title="boost/python/enum.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_def_visitor_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_enum_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="high_level_components.boost_python_docstring_options_h"></a><a class="link" href="boost_python_docstring_options_h.html" title="boost/python/docstring_options.hpp">boost/python/docstring_options.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options">Class
<code class="computeroutput"><span class="identifier">docstring_options</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_dostring_options_construct">Class
dostring_options constructors</a></span></dt>
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct">Class
docstring_options destructor</a></span></dt>
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier">Class
<code class="computeroutput"><span class="identifier">docstring_options</span></code> modifier
functions</a></span></dt>
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_docstring_options_h.introduction"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
Boost.Python supports user-defined docstrings with automatic appending
of C++ signatures. These features are enabled by default. The class docstring_options
is available to selectively suppress the user-defined docstrings, signatures,
or both.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_docstring_options_h.class_docstring_options"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options" title="Class docstring_options">Class
<code class="computeroutput"><span class="identifier">docstring_options</span></code></a>
</h3></div></div></div>
<p>
Controls the appearance of docstrings of wrapped functions and member functions
for the life-time of the instance. The instances are noncopyable to eliminate
the possibility of surprising side effects.
</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">docstring_options</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_all</span><span class="special">=</span><span class="keyword">true</span><span class="special">);</span>
<span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_signatures</span><span class="special">);</span>
<span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_py_signatures</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_cpp_signatures</span><span class="special">);</span>
<span class="special">~</span><span class="identifier">docstring_options</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_user_defined</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_user_defined</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_py_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_py_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_cpp_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_cpp_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_all</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_all</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="high_level_components.boost_python_docstring_options_h.class_dostring_options_construct"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_dostring_options_construct" title="Class dostring_options constructors">Class
dostring_options constructors</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_all</span><span class="special">=</span><span class="keyword">true</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 docstring_options object which controls the appearance
of function and member-function docstrings defined in the code that
follows. If show_all is true, both the user-defined docstrings and
the automatically generated Python and C++ signatures are shown.
If show_all is false the <code class="computeroutput"><span class="identifier">__doc__</span></code>
attributes are <code class="computeroutput"><span class="identifier">None</span></code>.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_signatures</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 <code class="computeroutput"><span class="identifier">docstring_options</span></code>
object which controls the appearance of function and member-function
docstrings defined in the code that follows. Iff <code class="computeroutput"><span class="identifier">show_user_defined</span></code>
is <code class="computeroutput"><span class="keyword">true</span></code>, the user-defined
docstrings are shown. Iff <code class="computeroutput"><span class="identifier">show_signatures</span></code>
is <code class="computeroutput"><span class="keyword">true</span></code>, Python and
C++ signatures are automatically added. If both <code class="computeroutput"><span class="identifier">show_user_defined</span></code>
and <code class="computeroutput"><span class="identifier">show_signatures</span></code>
are <code class="computeroutput"><span class="keyword">false</span></code>, the <code class="computeroutput"><span class="identifier">__doc__</span></code> attributes are <code class="computeroutput"><span class="identifier">None</span></code>.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_py_signatures</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_cpp_signatures</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 <code class="computeroutput"><span class="identifier">docstring_options</span></code>
object which controls the appearance of function and member-function
docstrings defined in the code that follows. Iff <code class="computeroutput"><span class="identifier">show_user_defined</span></code>
is <code class="computeroutput"><span class="keyword">true</span></code>, the user-defined
docstrings are shown. Iff <code class="computeroutput"><span class="identifier">show_py_signatures</span></code>
is <code class="computeroutput"><span class="keyword">true</span></code>, Python signatures
are automatically added. Iff <code class="computeroutput"><span class="identifier">show_cpp_signatures</span></code>
is true, C++ signatures are automatically added. If all parameters
are <code class="computeroutput"><span class="keyword">false</span></code>, the <code class="computeroutput"><span class="identifier">__doc__</span></code> attributes are <code class="computeroutput"><span class="identifier">None</span></code>.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct" title="Class docstring_options destructor">Class
docstring_options destructor</a>
</h3></div></div></div>
<pre class="programlisting"><span class="special">~</span><span class="identifier">docstring_options</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>
Restores the previous state of the docstring options. In particular,
if <code class="computeroutput"><span class="identifier">docstring_options</span></code>
instances are in nested C++ scopes the settings effective in the
enclosing scope are restored. If the last <code class="computeroutput"><span class="identifier">docstring_options</span></code>
instance goes out of scope the default "all on" settings
are restored.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier" title="Class docstring_options modifier functions">Class
<code class="computeroutput"><span class="identifier">docstring_options</span></code> modifier
functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">disable_user_defined</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_user_defined</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_py_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_py_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_cpp_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_cpp_signatures</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">disable_all</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">enable_all</span><span class="special">();</span>
</pre>
<p>
These member functions dynamically change the appearance of docstrings
in the code that follows. The <code class="computeroutput"><span class="special">*</span><span class="identifier">_user_defined</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="special">*</span><span class="identifier">_signatures</span><span class="special">()</span></code> member functions are provided for fine-grained
control. The <code class="computeroutput"><span class="special">*</span><span class="identifier">_all</span><span class="special">()</span></code> member functions are convenient shortcuts
to manipulate all settings simultaneously.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_docstring_options_h.example"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example" title="Example">Example</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.docstring_options_defined_at_com">Docstring
options defined at compile time</a></span></dt>
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.selective_suppressions">Selective
suppressions</a></span></dt>
<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.wrapping_from_multiple_c_scopes">Wrapping
from multiple C++ scopes</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="high_level_components.boost_python_docstring_options_h.example.docstring_options_defined_at_com"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.docstring_options_defined_at_com" title="Docstring options defined at compile time">Docstring
options defined at compile time</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">docstring_options</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span> <span class="special">{}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span>
<span class="special">{</span>
<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="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">(</span><span class="identifier">DEMO_DOCSTRING_SHOW_ALL</span><span class="special">);</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="string">"foo doc"</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
If compiled with <code class="computeroutput"><span class="special">-</span><span class="identifier">DDEMO_DOCSTRING_SHOW_ALL</span><span class="special">=</span><span class="keyword">true</span></code>:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">import</span> <span class="identifier">demo</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">foo</span><span class="special">()</span> <span class="special">-&gt;</span> <span class="identifier">None</span> <span class="special">:</span> <span class="identifier">foo</span> <span class="identifier">doc</span>
<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span>
<span class="identifier">foo</span><span class="special">(</span><span class="keyword">void</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="keyword">void</span>
</pre>
<p>
If compiled with <code class="computeroutput"><span class="special">-</span><span class="identifier">DDEMO_DOCSTRING_SHOW_ALL</span><span class="special">=</span><span class="keyword">false</span></code>:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">import</span> <span class="identifier">demo</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">None</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="high_level_components.boost_python_docstring_options_h.example.selective_suppressions"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.selective_suppressions" title="Selective suppressions">Selective
suppressions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">docstring_options</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">int</span> <span class="identifier">foo1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">foo2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">l</span><span class="special">);</span> <span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">foo3</span><span class="special">(</span><span class="keyword">float</span> <span class="identifier">f</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">f</span><span class="special">);</span> <span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">foo4</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">d</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">d</span><span class="special">);</span> <span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span>
<span class="special">{</span>
<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="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">;</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo1"</span><span class="special">,</span> <span class="identifier">foo1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"i"</span><span class="special">),</span> <span class="string">"foo1 doc"</span><span class="special">);</span>
<span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">disable_user_defined</span><span class="special">();</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo2"</span><span class="special">,</span> <span class="identifier">foo2</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"l"</span><span class="special">),</span> <span class="string">"foo2 doc"</span><span class="special">);</span>
<span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">disable_signatures</span><span class="special">();</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo3"</span><span class="special">,</span> <span class="identifier">foo3</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"f"</span><span class="special">),</span> <span class="string">"foo3 doc"</span><span class="special">);</span>
<span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">enable_user_defined</span><span class="special">();</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo4"</span><span class="special">,</span> <span class="identifier">foo4</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"d"</span><span class="special">),</span> <span class="string">"foo4 doc"</span><span class="special">);</span>
<span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">enable_py_signatures</span><span class="special">();</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo5"</span><span class="special">,</span> <span class="identifier">foo4</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"d"</span><span class="special">),</span> <span class="string">"foo5 doc"</span><span class="special">);</span>
<span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">disable_py_signatures</span><span class="special">();</span>
<span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">enable_cpp_signatures</span><span class="special">();</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo6"</span><span class="special">,</span> <span class="identifier">foo4</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"d"</span><span class="special">),</span> <span class="string">"foo6 doc"</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
Python code:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">import</span> <span class="identifier">demo</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo1</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">foo1</span><span class="special">(</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="identifier">i</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="keyword">int</span> <span class="special">:</span> <span class="identifier">foo1</span> <span class="identifier">doc</span>
<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span>
<span class="identifier">foo1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="keyword">int</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo2</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">foo2</span><span class="special">(</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="identifier">l</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="keyword">int</span> <span class="special">:</span>
<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span>
<span class="identifier">foo2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="keyword">int</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo3</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">None</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo4</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">foo4</span> <span class="identifier">doc</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo5</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">foo5</span><span class="special">(</span> <span class="special">(</span><span class="keyword">float</span><span class="special">)</span><span class="identifier">d</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="keyword">int</span> <span class="special">:</span> <span class="identifier">foo5</span> <span class="identifier">doc</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo6</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">foo6</span> <span class="identifier">doc</span>
<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span>
<span class="identifier">foo6</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">d</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="keyword">int</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="high_level_components.boost_python_docstring_options_h.example.wrapping_from_multiple_c_scopes"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.wrapping_from_multiple_c_scopes" title="Wrapping from multiple C++ scopes">Wrapping
from multiple C++ scopes</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">docstring_options</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">int</span> <span class="identifier">foo1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">foo2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">l</span><span class="special">);</span> <span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">bar1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">bar2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">l</span><span class="special">);</span> <span class="special">}</span>
<span class="keyword">namespace</span> <span class="special">{</span>
<span class="keyword">void</span> <span class="identifier">wrap_foos</span><span class="special">()</span>
<span class="special">{</span>
<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">// no docstring_options here</span>
<span class="comment">// -&gt; settings from outer C++ scope are in effect</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo1"</span><span class="special">,</span> <span class="identifier">foo1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"i"</span><span class="special">),</span> <span class="string">"foo1 doc"</span><span class="special">);</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo2"</span><span class="special">,</span> <span class="identifier">foo2</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"l"</span><span class="special">),</span> <span class="string">"foo2 doc"</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="identifier">wrap_bars</span><span class="special">()</span>
<span class="special">{</span>
<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="keyword">bool</span> <span class="identifier">show_user_defined</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>
<span class="keyword">bool</span> <span class="identifier">show_signatures</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span>
<span class="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">(</span><span class="identifier">show_user_defined</span><span class="special">,</span> <span class="identifier">show_signatures</span><span class="special">);</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"bar1"</span><span class="special">,</span> <span class="identifier">bar1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"i"</span><span class="special">),</span> <span class="string">"bar1 doc"</span><span class="special">);</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"bar2"</span><span class="special">,</span> <span class="identifier">bar2</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"l"</span><span class="special">),</span> <span class="string">"bar2 doc"</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
<span class="identifier">wrap_foos</span><span class="special">();</span>
<span class="identifier">wrap_bars</span><span class="special">();</span>
<span class="special">}</span>
</pre>
<p>
Python code:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">import</span> <span class="identifier">demo</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo1</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">None</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo2</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">None</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">bar1</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">bar1</span> <span class="identifier">doc</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">bar2</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">bar2</span> <span class="identifier">doc</span>
</pre>
</div>
</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_def_visitor_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_enum_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,217 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/enum.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_docstring_options_h.html" title="boost/python/docstring_options.hpp">
<link rel="next" href="boost_python_errors_hpp.html" title="boost/python/errors.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_docstring_options_h.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_errors_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="high_level_components.boost_python_enum_hpp"></a><a class="link" href="boost_python_enum_hpp.html" title="boost/python/enum.hpp">boost/python/enum.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum">Class
template <code class="computeroutput"><span class="identifier">enum_</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_constructors">Class
template <code class="computeroutput"><span class="identifier">enum_</span></code> constructors</a></span></dt>
<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun">Class
template <code class="computeroutput"><span class="identifier">enum_</span></code> modifier functions</a></span></dt>
<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_enum_hpp.introduction"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
&lt;boost/python/enum.hpp&gt; defines the interface through which users
expose their C++ enumeration types to Python. It declares the <code class="computeroutput"><span class="identifier">enum_</span></code> class template, which is parameterized
on the enumeration type being exposed.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_enum_hpp.class_template_enum"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum" title="Class template enum_">Class
template <code class="computeroutput"><span class="identifier">enum_</span></code></a>
</h3></div></div></div>
<p>
Creates a Python class derived from Python's <code class="computeroutput"><span class="keyword">int</span></code>
type which is associated with the C++ type passed as its first parameter.
</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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">enum_</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span>
<span class="special">{</span>
<span class="identifier">enum_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
<span class="identifier">enum_</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">value</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span>
<span class="identifier">enum_</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">export_values</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="high_level_components.boost_python_enum_hpp.class_template_enum_constructors"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_constructors" title="Class template enum_ constructors">Class
template <code class="computeroutput"><span class="identifier">enum_</span></code> constructors</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">enum_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</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>
name is an <a class="link" href="../glossary.html#ntbs">ntbs</a> which conforms to Python's
<a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier
naming rules</a>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Constructs an <code class="computeroutput"><span class="identifier">enum_</span></code>
object holding a Python extension type derived from <code class="computeroutput"><span class="keyword">int</span></code> which is named <code class="computeroutput"><span class="identifier">name</span></code>.
The named attribute of the <a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">current
scope</a> is bound to the new extension type.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun" title="Class template enum_ modifier functions">Class
template <code class="computeroutput"><span class="identifier">enum_</span></code> modifier functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">enum_</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">value</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</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>
name is an <a class="link" href="../glossary.html#ntbs">ntbs</a> which conforms to Python's
<a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier
naming rules</a>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
adds an instance of the wrapped enumeration type with value x to
the type's dictionary as the named attribute.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="identifier">enum_</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">export_values</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>
sets attributes in the <a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">current
scope</a> with the same names and values as all enumeration values
exposed so far by calling value().
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_enum_hpp.example"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
C++ module definition
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">enum</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<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="keyword">enum</span> <span class="identifier">color</span> <span class="special">{</span> <span class="identifier">red</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">green</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">blue</span> <span class="special">=</span> <span class="number">4</span> <span class="special">};</span>
<span class="identifier">color</span> <span class="identifier">identity_</span><span class="special">(</span><span class="identifier">color</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">enums</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">enum_</span><span class="special">&lt;</span><span class="identifier">color</span><span class="special">&gt;(</span><span class="string">"color"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">value</span><span class="special">(</span><span class="string">"red"</span><span class="special">,</span> <span class="identifier">red</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">value</span><span class="special">(</span><span class="string">"green"</span><span class="special">,</span> <span class="identifier">green</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">export_values</span><span class="special">()</span>
<span class="special">.</span><span class="identifier">value</span><span class="special">(</span><span class="string">"blue"</span><span class="special">,</span> <span class="identifier">blue</span><span class="special">)</span>
<span class="special">;</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"identity"</span><span class="special">,</span> <span class="identifier">identity_</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
Interactive Python:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">enums</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">red</span><span class="special">)</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span><span class="special">)</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">green</span><span class="special">)</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span><span class="special">)</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">blue</span><span class="special">)</span>
<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span>
<span class="identifier">File</span> <span class="string">"&lt;stdin&gt;"</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span>
<span class="identifier">NameError</span><span class="special">:</span> <span class="identifier">name</span> <span class="char">'blue'</span> <span class="identifier">is</span> <span class="keyword">not</span> <span class="identifier">defined</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">blue</span><span class="special">)</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">blue</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">1</span><span class="special">))</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">2</span><span class="special">))</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">3</span><span class="special">))</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">(</span><span class="number">3</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">4</span><span class="special">))</span>
<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">blue</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">identity</span><span class="special">(</span><span class="number">1</span><span class="special">)</span>
<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span>
<span class="identifier">File</span> <span class="string">"&lt;stdin&gt;"</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span>
<span class="identifier">TypeError</span><span class="special">:</span> <span class="identifier">bad</span> <span class="identifier">argument</span> <span class="identifier">type</span> <span class="keyword">for</span> <span class="identifier">built</span><span class="special">-</span><span class="identifier">in</span> <span class="identifier">operation</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_docstring_options_h.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_errors_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,278 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/errors.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_enum_hpp.html" title="boost/python/enum.hpp">
<link rel="next" href="boost_python_exception_translato.html" title="boost/python/exception_translator.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_enum_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_exception_translato.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="high_level_components.boost_python_errors_hpp"></a><a class="link" href="boost_python_errors_hpp.html" title="boost/python/errors.hpp">boost/python/errors.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set">Class
<code class="computeroutput"><span class="identifier">error_already_set</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions">Functions</a></span></dt>
<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_errors_hpp.introduction"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
&lt;boost/python/errors.hpp&gt; provides types and functions for managing
and translating between Python and C++ exceptions. This is relatively low-level
functionality that is mostly used internally by Boost.Python. Users should
seldom need it.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_errors_hpp.class_error_already_set"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">Class
<code class="computeroutput"><span class="identifier">error_already_set</span></code></a>
</h3></div></div></div>
<p>
error_already_set is an exception type which can be thrown to indicate
that a Python error has occurred. If thrown, the precondition is that
<a href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71" target="_top">PyErr_Occurred()</a>
returns a value convertible to <code class="computeroutput"><span class="keyword">true</span></code>.
Portable code shouldn't throw this exception type directly, but should
instead use <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions" title="Functions">throw_error_already_set()</a>,
below.
</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">error_already_set</span> <span class="special">{};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_errors_hpp.functions"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions" title="Functions">Functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">bool</span> <span class="identifier">handle_exception</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">f</span><span class="special">)</span> <span class="keyword">throw</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">handle_exception</span><span class="special">()</span> <span class="keyword">throw</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>
The first form requires that the expression function0&lt;void&gt;(f)
is valid. The second form requires that a C++ exception is currently
being handled (see section 15.1 in the C++ standard).
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
The first form calls f() inside a try block which first attempts
to use all registered <a class="link" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp">exception
translators</a>. If none of those translates the exception, the
catch clauses then set an appropriate Python exception for the C++
exception caught, returning true if an exception was thrown, false
otherwise. The second form passes a function which rethrows the exception
currently being handled to the first form.
</p></dd>
<dt><span class="term">Postconditions</span></dt>
<dd><p>
No exception is being handled
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
nothing
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
At inter-language boundaries it is important to ensure that no C++
exceptions escape, since the calling language usually doesn't have
the equipment necessary to properly unwind the stack. Use handle_exception
to manage exception translation whenever your C++ code is called
directly from the Python API. This is done for you automatically
by the usual function wrapping facilities: <a class="link" href="../function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions" title="Functions">make_function()</a>,
<a class="link" href="../function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions" title="Functions">make_constructor()</a>,
<a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions" title="Functions">def()</a>
and <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions">class_::def()</a>.
The second form can be more convenient to use (see the example below),
but various compilers have problems when exceptions are rethrown
from within an enclosing try block.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">expect_non_null</span><span class="special">(</span><span class="identifier">T</span><span class="special">*</span> <span class="identifier">x</span><span class="special">);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Returns</span></dt>
<dd><p>
x
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
error_already_set() iff x == 0.
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
Simplifies error-handling when calling functions in the Python/C
API which return 0 on error.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">throw_error_already_set</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>
throw error_already_set();
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
Simplifies error-handling when calling functions in the Python/C
API which return 0 on error.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">throw_error_already_set</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>
throw error_already_set();
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
Many platforms and compilers are not able to consistently catch exceptions
thrown across shared library boundaries. Using this function from
the Boost.Python library ensures that the appropriate catch block
in handle_exception() can catch the exception.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_errors_hpp.example"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">errors</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">handle</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="comment">// Returns a std::string which has the same value as obj's "__name__"</span>
<span class="comment">// attribute.</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">obj</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// throws if there's no __name__ attribute</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">expect_non_null</span><span class="special">(</span>
<span class="identifier">PyObject_GetAttrString</span><span class="special">(</span><span class="identifier">obj</span><span class="special">.</span><span class="identifier">ptr</span><span class="special">(),</span> <span class="string">"__name__"</span><span class="special">));</span>
<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">PyString_AsString</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">s</span> <span class="special">!=</span> <span class="number">0</span><span class="special">)</span>
<span class="identifier">Py_DECREF</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span>
<span class="comment">// throws if it's not a Python string</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">result</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">expect_non_null</span><span class="special">(</span>
<span class="identifier">PyString_AsString</span><span class="special">(</span><span class="identifier">p</span><span class="special">)));</span>
<span class="identifier">Py_DECREF</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span> <span class="comment">// Done with p</span>
<span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">//</span>
<span class="comment">// Demonstrate form 1 of handle_exception</span>
<span class="comment">//</span>
<span class="comment">// Place into result a Python Int object whose value is 1 if a and b have</span>
<span class="comment">// identical "__name__" attributes, 0 otherwise.</span>
<span class="keyword">void</span> <span class="identifier">same_name_impl</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*&amp;</span> <span class="identifier">result</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">b</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">result</span> <span class="special">=</span> <span class="identifier">PyInt_FromLong</span><span class="special">(</span>
<span class="identifier">get_name</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">a2</span><span class="special">));</span>
<span class="special">}</span>
<span class="identifier">object</span> <span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">p</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">handle</span><span class="special">&lt;&gt;(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special">(</span><span class="identifier">a1</span><span class="special">)));</span>
<span class="special">}</span>
<span class="comment">// This is an example Python 'C' API interface function</span>
<span class="keyword">extern</span> <span class="string">"C"</span> <span class="identifier">PyObject</span><span class="special">*</span>
<span class="identifier">same_name</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">keywords</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a1</span><span class="special">;</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a2</span><span class="special">;</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">if</span> <span class="special">(!</span><span class="identifier">PyArg_ParseTuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="keyword">const_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="string">"OO"</span><span class="special">),</span> <span class="special">&amp;</span><span class="identifier">a1</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">a2</span><span class="special">))</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="comment">// Use boost::bind to make an object compatible with</span>
<span class="comment">// boost::Function0&lt;void&gt;</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">handle_exception</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;(</span><span class="identifier">same_name_impl</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">result</span><span class="special">),</span> <span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a1</span><span class="special">),</span> <span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a2</span><span class="special">))))</span>
<span class="special">{</span>
<span class="comment">// an exception was thrown; the Python error was set by</span>
<span class="comment">// handle_exception()</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">//</span>
<span class="comment">// Demonstrate form 2 of handle_exception. Not well-supported by all</span>
<span class="comment">// compilers.</span>
<span class="comment">//</span>
<span class="keyword">extern</span> <span class="string">"C"</span> <span class="identifier">PyObject</span><span class="special">*</span>
<span class="identifier">same_name2</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">keywords</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a1</span><span class="special">;</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a2</span><span class="special">;</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">if</span> <span class="special">(!</span><span class="identifier">PyArg_ParseTuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="keyword">const_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="string">"OO"</span><span class="special">),</span> <span class="special">&amp;</span><span class="identifier">a1</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">a2</span><span class="special">))</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">try</span> <span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">PyInt_FromLong</span><span class="special">(</span>
<span class="identifier">get_name</span><span class="special">(</span><span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a1</span><span class="special">))</span> <span class="special">==</span> <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a2</span><span class="special">)));</span>
<span class="special">}</span>
<span class="keyword">catch</span><span class="special">(...)</span>
<span class="special">{</span>
<span class="comment">// If an exception was thrown, translate it to Python</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">handle_exception</span><span class="special">();</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</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_enum_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_exception_translato.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,130 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/exception_translator.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_errors_hpp.html" title="boost/python/errors.hpp">
<link rel="next" href="boost_python_init_hpp.html" title="boost/python/init.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_errors_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_init_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="high_level_components.boost_python_exception_translato"></a><a class="link" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp">boost/python/exception_translator.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran">Function
<code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_exception_translato.introduction"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
As described <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction" title="Introduction">here</a>,
it is important to make sure that exceptions thrown by C++ code do not
pass into the Python interpreter core. By default, Boost.Python translates
all C++ exceptions thrown by wrapped functions and module init functions
into Python, but the default translators are extremely limited: most C++
exceptions will appear in Python as a <a href="http://www.python.org/doc/current/lib/module-exceptions.html" target="_top">RuntimeError</a>
exception whose representation is 'Unidentifiable C++ Exception'. To produce
better error messages, users can register additional exception translators
as described below.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_exception_translato.function_register_exception_tran"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran" title="Function register_exception_translator">Function
<code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ExceptionType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Translate</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">register_exception_translator</span><span class="special">(</span><span class="identifier">Translate</span> <span class="identifier">translate</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>
Translate is CopyConstructible, and the following code must be well-formed:
</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">ExceptionType</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> <span class="special">}</span></pre>
<p>
. The expression <code class="computeroutput"><span class="identifier">translate</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> must either throw a C++ exception,
or a subsequent call to <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span></code> must return 1.
</p>
</dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Adds a copy of translate to the sequence of exception translators
tried when Boost.Python catches an exception that is about to pass
into Python's core interpreter. The new translator will get "first
shot" at translating all exceptions matching the catch clause
shown above. Any subsequently-registered translators will be allowed
to translate the exception earlier. A translator which cannot translate
a given C++ exception can re-throw it, and it will be handled by
a translator which was registered earlier (or by the default translator).
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_exception_translato.example"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">exception_translator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">exception</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">my_exception</span> <span class="special">:</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span>
<span class="special">{</span>
<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">what</span><span class="special">()</span> <span class="keyword">throw</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"One of my exceptions"</span><span class="special">;</span> <span class="special">}</span>
<span class="special">};</span>
<span class="keyword">void</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">my_exception</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// Use the Python 'C' API to set up an exception object</span>
<span class="identifier">PyErr_SetString</span><span class="special">(</span><span class="identifier">PyExc_RuntimeError</span><span class="special">,</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">());</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="identifier">something_which_throws</span><span class="special">()</span>
<span class="special">{</span>
<span class="special">...</span>
<span class="keyword">throw</span> <span class="identifier">my_exception</span><span class="special">();</span>
<span class="special">...</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">exception_translator_ext</span><span class="special">)</span>
<span class="special">{</span>
<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="identifier">register_exception_translator</span><span class="special">&lt;</span><span class="identifier">my_exception</span><span class="special">&gt;(&amp;</span><span class="identifier">translate</span><span class="special">);</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"something_which_throws"</span><span class="special">,</span> <span class="identifier">something_which_throws</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_errors_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_init_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,233 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/init.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp">
<link rel="next" href="boost_python_iterator_hpp.html" title="boost/python/iterator.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_exception_translato.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_iterator_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="high_level_components.boost_python_init_hpp"></a><a class="link" href="boost_python_init_hpp.html" title="boost/python/init.hpp">boost/python/init.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init">Class
template <code class="computeroutput"><span class="identifier">init</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional">Class
template <code class="computeroutput"><span class="identifier">optional</span></code> </a></span></dt>
<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_init_hpp.introduction"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions">init-expressions</a></span></dt></dl></div>
<p>
&lt;boost/python/init.hpp&gt; defines the interface for exposing C++ constructors
to Python as extension class <code class="computeroutput"><span class="identifier">__init__</span></code>
functions.
</p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="high_level_components.boost_python_init_hpp.introduction.init_expressions"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">init-expressions</a>
</h4></div></div></div>
<p>
An init-expression is used to describe a family of <code class="computeroutput"><span class="identifier">__init__</span></code>
methods to be generated for an extension class, and the result has the
following properties:
</p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">docstring</span></dt>
<dd><p>
An <a class="link" href="../glossary.html#ntbs">ntbs</a> whose value will bound to the
method's <code class="computeroutput"><span class="identifier">__doc__</span></code>
attribute
</p></dd>
<dt><span class="term">keywords</span></dt>
<dd><p>
A <a class="link" href="../function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expression</a>
which will be used to name (a trailing subsequence of) the arguments
to the generated <code class="computeroutput"><span class="identifier">__init__</span></code>
function(s).
</p></dd>
<dt><span class="term">call_policies</span></dt>
<dd><p>
An instance of a model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>.
</p></dd>
<dt><span class="term">argument_types</span></dt>
<dd><p>
An MPL sequence of C++ argument types which will be used to construct
the wrapped C++ object. An init expression has one or more valid
prefixes which are given by a sequence of prefixes of its argument
types.
</p></dd>
</dl>
</div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_init_hpp.class_template_init"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init" title="Class template init">Class
template <code class="computeroutput"><span class="identifier">init</span></code></a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_constructors">Class
template <code class="computeroutput"><span class="identifier">init</span></code> constructors</a></span></dt>
<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_observer_fun">Class
template <code class="computeroutput"><span class="identifier">init</span></code> observer
functions</a></span></dt>
</dl></div>
<p>
A MPL sequence which can be used to specify a family of one or more __init__
functions. Only the last Ti supplied may be an instantiation of optional&lt;...&gt;.
</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">template</span> <span class="special">&lt;</span><span class="identifier">T1</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">,...</span><span class="identifier">Tn</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">init</span>
<span class="special">{</span>
<span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">&gt;</span> <span class="identifier">init</span><span class="special">(</span><span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">kw</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">&gt;</span> <span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">,</span> <span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">kw</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">CallPolicies</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">CallPolicies</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">policies</span><span class="special">)</span> <span class="keyword">const</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="high_level_components.boost_python_init_hpp.class_template_init.class_template_init_constructors"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_constructors" title="Class template init constructors">Class
template <code class="computeroutput"><span class="identifier">init</span></code> constructors</a>
</h4></div></div></div>
<pre class="programlisting"><span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">&gt;</span> <span class="identifier">init</span><span class="special">(</span><span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">kw</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">&gt;</span> <span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">,</span> <span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">kw</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>
If supplied, doc is an <a class="link" href="../glossary.html#ntbs">ntbs</a>. If supplied,
kw is the result of a
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd>
<p>
The result is an init-expression whose docstring is doc and whose
keywords are a reference to kw. If the first form is used, the
resulting expression's keywords are empty. The expression's call
policies are an instance of <a class="link" href="../function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici" title="boost/python/default_call_policies.hpp">default_call_policies</a>.
If Tn is <a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional" title="Class template optional">optional&lt;U1,
U2,... Um&gt;</a>, the expression's valid prefixes are given
by:
</p>
<pre class="programlisting"><span class="special">(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span><span class="special">),</span> <span class="special">(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span> <span class="special">,</span> <span class="identifier">U1</span><span class="special">),</span> <span class="special">(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span> <span class="special">,</span> <span class="identifier">U1</span><span class="special">,</span> <span class="identifier">U2</span><span class="special">),</span> <span class="special">...(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span> <span class="special">,</span> <span class="identifier">U1</span><span class="special">,</span> <span class="identifier">U2</span><span class="special">,...</span><span class="identifier">Um</span><span class="special">)</span></pre>
<p>
. Otherwise, the expression has one valid prefix given by the template
arguments the user specified.
</p>
</dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="high_level_components.boost_python_init_hpp.class_template_init.class_template_init_observer_fun"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_observer_fun" title="Class template init observer functions">Class
template <code class="computeroutput"><span class="identifier">init</span></code> observer
functions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">policies</span><span class="special">)</span> <span class="keyword">const</span>
</pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
Policies is a model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Returns a new <a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">init-expression</a>
with all the same properties as the init object except that its
call policies are replaced by a reference to policies.
</p></dd>
</dl>
</div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_init_hpp.class_template_optional"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional" title="Class template optional">Class
template <code class="computeroutput"><span class="identifier">optional</span></code> </a>
</h3></div></div></div>
<p>
A MPL sequence which can be used to specify the optional arguments to an
__init__ function.
</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">template</span> <span class="special">&lt;</span><span class="identifier">T1</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">,...</span><span class="identifier">Tn</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">optional</span> <span class="special">{};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_init_hpp.example"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
Given the C++ declarations:
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">;</span>
<span class="keyword">class</span> <span class="identifier">X</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">X</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Y</span><span class="special">*</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_y</span><span class="special">(</span><span class="identifier">y</span><span class="special">)</span> <span class="special">{}</span>
<span class="identifier">X</span><span class="special">(</span><span class="keyword">double</span><span class="special">);</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Y</span><span class="special">*</span> <span class="identifier">m_y</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
A corresponing Boost.Python extension class can be created with:
</p>
<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="identifier">class_</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;(</span><span class="string">"X"</span><span class="special">,</span> <span class="string">"This is X's docstring."</span><span class="special">,</span>
<span class="identifier">init</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*&gt;(</span><span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span><span class="string">"y"</span><span class="special">),</span> <span class="string">"X.__init__'s docstring"</span><span class="special">)[</span>
<span class="identifier">with_custodian_and_ward</span><span class="special">&lt;</span><span class="number">1</span><span class="special">,</span><span class="number">3</span><span class="special">&gt;()]</span>
<span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;())</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_exception_translato.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_iterator_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,398 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/iterator.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_init_hpp.html" title="boost/python/init.hpp">
<link rel="next" href="boost_python_module_hpp.html" title="boost/python/module.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_init_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_module_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="high_level_components.boost_python_iterator_hpp"></a><a class="link" href="boost_python_iterator_hpp.html" title="boost/python/iterator.hpp">boost/python/iterator.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator">Class
template <code class="computeroutput"><span class="identifier">iterator</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator_construc">Class
template iterator constructors</a></span></dt>
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators">Class
template <code class="computeroutput"><span class="identifier">iterators</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_">Class
template iterators nested types</a></span></dt>
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_static_">Class
template iterators static functions</a></span></dt>
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.functions">Functions</a></span></dt>
<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_iterator_hpp.introduction"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
&lt;boost/python/iterator.hpp&gt; provides types and functions for creating
<a href="http://www.python.org/doc/current/lib/typeiter.html" target="_top">Python
iterators</a> from C++ Containers and Iterators. Note that if your
<code class="computeroutput"><span class="identifier">class_</span></code> supports random-access
iterators, implementing <a href="http://www.python.org/doc/current/ref/sequence-types.html#l2h-128" target="_top">__getitem__</a>
(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" target="_top"><code class="computeroutput"><span class="identifier">iter</span><span class="special">()</span></code></a>),
and each access can be range-checked, leaving no possiblity of accessing
through an invalidated C++ iterator.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_iterator_hpp.class_template_iterator"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator" title="Class template iterator">Class
template <code class="computeroutput"><span class="identifier">iterator</span></code></a>
</h3></div></div></div>
<p>
Instances of <code class="computeroutput"><span class="identifier">iterator</span><span class="special">&lt;</span><span class="identifier">C</span><span class="special">,</span><span class="identifier">P</span><span class="special">&gt;</span></code> hold a reference to a callable Python
object which, when invoked from Python, expects a single argument c convertible
to C and creates a Python iterator that traverses <code class="computeroutput"><span class="special">[</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">())</span></code>. The optional <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>
<code class="computeroutput"><span class="identifier">P</span></code> can be used to control
how elements are returned during iteration.
</p>
<p>
In the table below, c is an instance of Container.
</p>
<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>
<code class="computeroutput"><span class="special">[</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span></code>) is a valid Iterator range.
</p>
</td>
<td>
<p>
The result will convert its argument to c and call c.begin()
and c.end() to acquire iterators. To invoke Container's const
<code class="computeroutput"><span class="identifier">begin</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">end</span><span class="special">()</span></code>
functions, make it const.
</p>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
NextPolicies
</p>
</td>
<td>
<p>
A default-constructible model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>.
</p>
</td>
<td>
<p>
Applied to the resulting iterators' <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code> method.
</p>
</td>
<td>
<p>
An unspecified model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>
which always makes a copy of the result of deferencing the underlying
C++ iterator
</p>
</td>
</tr>
</tbody>
</table></div>
<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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">NextPolicies</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator</span> <span class="special">:</span> <span class="identifier">object</span>
<span class="special">{</span>
<span class="identifier">iterator</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="high_level_components.boost_python_iterator_hpp.class_template_iterator_construc"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator_construc" title="Class template iterator constructors">Class
template iterator constructors</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">iterator</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>
Initializes its base class with the result of:
</p>
<pre class="programlisting"><span class="identifier">range</span><span class="special">&lt;</span><span class="identifier">NextPolicies</span><span class="special">&gt;(&amp;</span><span class="identifier">iterators</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;::</span><span class="identifier">begin</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">iterators</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;::</span><span class="identifier">end</span><span class="special">)</span></pre>
</dd>
<dt><span class="term">Postconditions</span></dt>
<dd><p>
<code class="computeroutput"><span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">()</span></code>
points to a Python callable object which creates a Python iterator
as described above.
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
Provides an easy way to create iterators for the common case where
a C++ class being wrapped provides <code class="computeroutput"><span class="identifier">begin</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">end</span><span class="special">()</span></code>.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_iterator_hpp.class_template_iterators"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators" title="Class template iterators">Class
template <code class="computeroutput"><span class="identifier">iterators</span></code></a>
</h3></div></div></div>
<p>
A utility class template which provides a way to reliably call its argument's
<code class="computeroutput"><span class="identifier">begin</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">end</span><span class="special">()</span></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 class="computeroutput"><span class="identifier">iterators</span><span class="special">&lt;&gt;</span></code>
can be particularly helpful when wrapping them.
</p>
<p>
In the table below, x is an instance of C.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Required Valid Expression
</p>
</th>
<th>
<p>
Type
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
x.begin()
</p>
</td>
<td>
<p>
Convertible to C::const_iterator if C is a const type; convertible
to C::iterator otherwise.
</p>
</td>
</tr>
<tr>
<td>
<p>
x.end()
</p>
</td>
<td>
<p>
Convertible to C::const_iterator if C is a const type; convertible
to C::iterator otherwise.
</p>
</td>
</tr>
</tbody>
</table></div>
<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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterators</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">iterator</span><span class="special">;</span>
<span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">C</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">end</span><span class="special">(</span><span class="identifier">C</span><span class="special">&amp;</span> <span class="identifier">x</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="high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_" title="Class template iterators nested types">Class
template iterators nested types</a>
</h3></div></div></div>
<p>
If C is a const type,
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">iterator</span><span class="special">;</span></pre>
<p>
Otherwise:
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">iterator</span><span class="special">;</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_iterator_hpp.class_template_iterators_static_"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_static_" title="Class template iterators static functions">Class
template iterators static functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">C</span><span class="special">&amp;);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()</span></code>
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">end</span><span class="special">(</span><span class="identifier">C</span><span class="special">&amp;);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span></code>
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_iterator_hpp.functions"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.functions" title="Functions">Functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">NextPolicies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor2</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">range</span><span class="special">(</span><span class="identifier">Accessor1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Accessor2</span> <span class="identifier">finish</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">NextPolicies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor2</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">range</span><span class="special">(</span><span class="identifier">Accessor1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Accessor2</span> <span class="identifier">finish</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Accessor1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor2</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">range</span><span class="special">(</span><span class="identifier">Accessor1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Accessor2</span> <span class="identifier">finish</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>
NextPolicies is a default-constructible model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd>
<p>
The first form creates a Python callable object which, when invoked,
converts its argument to a Target object x, and creates a Python
iterator which traverses <code class="computeroutput"><span class="special">[</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span><span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">finish</span><span class="special">,</span><span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">))</span></code>,
applying NextPolicies to the iterator's <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code> function. The second form is identical
to the first, except that Target is deduced from Accessor1 as follows:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
If Accessor1 is a function type, Target is the type of its first
argument.
</li>
<li class="listitem">
If Accessor1 is a data member pointer of the form <code class="computeroutput"><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*)</span></code>,
Target is identical to <code class="computeroutput"><span class="identifier">T</span></code>.
</li>
<li class="listitem">
If Accessor1 is a member function pointer of the form <code class="computeroutput"><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*)(</span><span class="identifier">arguments</span><span class="special">...)</span>
<span class="identifier">cv</span><span class="special">-</span><span class="identifier">opt</span></code>, where cv-opt is an optional
cv-qualifier, Target is identical to <code class="computeroutput"><span class="identifier">T</span></code>.
</li>
</ol></div>
<p>
The third form is identical to the second, except that NextPolicies
is an unspecified model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>
which always makes a copy of the result of deferencing the underlying
C++ iterator
</p>
</dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
The use of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">()</span></code> allows C++ iterators to be accessed
through functions, member functions or data member pointers. Customization
of NextPolicies (e.g. using <a class="link" href="../function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r" title="Class template return_internal_reference">return_internal_reference</a>)
is useful when it is expensive to copy sequence elements of a wrapped
class type. Customization of Target is useful when Accessor1 is a
function object, or when a base class of the intended target type
would otherwise be deduced.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_iterator_hpp.example"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<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="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">class_</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="special">&gt;(</span><span class="string">"dvec"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"__iter__"</span><span class="special">,</span> <span class="identifier">iterator</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="special">&gt;())</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_init_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_module_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,111 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/module.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_iterator_hpp.html" title="boost/python/iterator.hpp">
<link rel="next" href="boost_python_operators_hpp.html" title="boost/python/operators.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_operators_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="high_level_components.boost_python_module_hpp"></a><a class="link" href="boost_python_module_hpp.html" title="boost/python/module.hpp">boost/python/module.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.macros">Macros</a></span></dt>
<dt><span class="section"><a href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.examples">Examples</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_module_hpp.introduction"></a><a class="link" href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
This header provides the basic facilities needed to create a Boost.Python
extension module.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_module_hpp.macros"></a><a class="link" href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.macros" title="Macros">Macros</a>
</h3></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
is used to declare Python <a href="http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000" target="_top">module
initialization functions</a>. The name argument must exactly match
the name of the module to be initialized, and must conform to Python's
<a href="http://www.python.org/doc/2.2/ref/identifiers.html" target="_top">identifier
naming rules</a>. Where you would normally write
</p>
<pre class="programlisting"><span class="keyword">extern</span> <span class="string">"C"</span> <span class="keyword">void</span> <span class="identifier">initname</span><span class="special">()</span>
<span class="special">{</span>
<span class="special">...</span>
<span class="special">}</span>
</pre>
<p>
Boost.Python modules should be initialized with
</p>
<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span>
<span class="special">{</span>
<span class="special">...</span>
<span class="special">}</span>
</pre>
<p>
This macro generates two functions in the scope where it is used: <code class="computeroutput"><span class="keyword">extern</span> <span class="string">"C"</span>
<span class="keyword">void</span> <span class="identifier">initname</span><span class="special">()</span></code>, and <code class="computeroutput"><span class="keyword">void</span>
<span class="identifier">init_module_name</span><span class="special">()</span></code>,
whose body must follow the macro invocation. <code class="computeroutput"><span class="identifier">init_name</span></code>
passes <code class="computeroutput"><span class="identifier">init_module_name</span></code>
to <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions" title="Functions">handle_exception()</a>
so that any C++ exceptions generated are safely processeed. During the
body of <code class="computeroutput"><span class="identifier">init_name</span></code>, the
<a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">current scope</a>
refers to the module being initialized.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_module_hpp.examples"></a><a class="link" href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.examples" title="Examples">Examples</a>
</h3></div></div></div>
<p>
C++ module definition:
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">xxx</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">throw</span> <span class="string">"something bad happened"</span>
<span class="special">}</span>
</pre>
<p>
Interactive Python:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">import</span> <span class="identifier">xxx</span>
<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span>
<span class="identifier">File</span> <span class="string">""</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span>
<span class="identifier">RuntimeError</span><span class="special">:</span> <span class="identifier">Unidentifiable</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">Exception</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_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_operators_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,160 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/scope.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_operators_hpp.html" title="boost/python/operators.hpp">
<link rel="next" href="boost_python_stl_iterator_hpp.html" title="boost/python/stl_iterator.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_operators_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_stl_iterator_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="high_level_components.boost_python_scope_hpp"></a><a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">boost/python/scope.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope">Class
<code class="computeroutput"><span class="identifier">scope</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des">Class
scope constructors and destructor</a></span></dt>
<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_scope_hpp.introduction"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
Defines facilities for querying and controlling the Python scope (namespace)
which will contain new wrapped classes and functions.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_scope_hpp.class_scope"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope" title="Class scope">Class
<code class="computeroutput"><span class="identifier">scope</span></code></a>
</h3></div></div></div>
<p>
The scope class has an associated global Python object which controls the
Python namespace in which new extension classes and wrapped functions will
be defined as attributes. Default-constructing a new scope object binds
it to the associated global Python object. Constructing a scope object
with an argument changes the associated global Python object to the one
held by the argument, until the lifetime of the scope object ends, at which
time the associated global Python object reverts to what it was before
the scope object was constructed.
</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">scope</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">scope</span><span class="special">(</span><span class="identifier">scope</span> <span class="keyword">const</span><span class="special">&amp;);</span>
<span class="identifier">scope</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&amp;);</span>
<span class="identifier">scope</span><span class="special">();</span>
<span class="special">~</span><span class="identifier">scope</span><span class="special">()</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">scope</span> <span class="keyword">const</span><span class="special">&amp;);</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des" title="Class scope constructors and destructor">Class
scope constructors and destructor</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">scope</span><span class="special">(</span><span class="identifier">scope</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">explicit</span> <span class="identifier">scope</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
</pre>
<p>
Stores a reference to the current associated scope object, and sets the
associated scope object to the one referred to by x.ptr(). The object base
class is initialized with x.
</p>
<pre class="programlisting"><span class="identifier">scope</span><span class="special">();</span></pre>
<p>
Stores a reference to the current associated scope object. The object base
class is initialized with the current associated scope object. Outside
any module initialization function, the current associated Python object
is None.
</p>
<pre class="programlisting"><span class="special">~</span><span class="identifier">scope</span><span class="special">()</span></pre>
<p>
Sets the current associated Python object to the stored object.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_scope_hpp.example"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
The following example shows how scope setting can be used to define nested
classes.
</p>
<p>
C++ Module definition:
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">scope</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<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="keyword">struct</span> <span class="identifier">X</span>
<span class="special">{</span>
<span class="keyword">void</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{}</span>
<span class="keyword">struct</span> <span class="identifier">Y</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">g</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="number">42</span><span class="special">;</span> <span class="special">}</span> <span class="special">};</span>
<span class="special">};</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">nested</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// add some constants to the current (module) scope</span>
<span class="identifier">scope</span><span class="special">().</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"yes"</span><span class="special">)</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>
<span class="identifier">scope</span><span class="special">().</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"no"</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="comment">// Change the current scope </span>
<span class="identifier">scope</span> <span class="identifier">outer</span>
<span class="special">=</span> <span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;(</span><span class="string">"X"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">)</span>
<span class="special">;</span>
<span class="comment">// Define a class Y in the current scope, X</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">Y</span><span class="special">&gt;(</span><span class="string">"Y"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"g"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">Y</span><span class="special">::</span><span class="identifier">g</span><span class="special">)</span>
<span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
Interactive Python:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">import</span> <span class="identifier">nested</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">nested</span><span class="special">.</span><span class="identifier">yes</span>
<span class="number">1</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">nested</span><span class="special">.</span><span class="identifier">X</span><span class="special">.</span><span class="identifier">Y</span><span class="special">()</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">g</span><span class="special">()</span>
<span class="number">42</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_operators_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_stl_iterator_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,311 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/stl_iterator.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">
<link rel="next" href="boost_python_wrapper_hpp.html" title="boost/python/wrapper.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/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost_python_scope_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_wrapper_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="high_level_components.boost_python_stl_iterator_hpp"></a><a class="link" href="boost_python_stl_iterator_hpp.html" title="boost/python/stl_iterator.hpp">boost/python/stl_iterator.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code>
constructors</a></span></dt>
<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code>
modifiers</a></span></dt>
<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code>
observers</a></span></dt>
<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_stl_iterator_hpp.introduction"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
&lt;boost/python/stl_iterator.hpp&gt; provides types for creating C++ Iterators
from <a href="http://www.python.org/doc/current/lib/typeiter.html" target="_top">Python
iterables</a>.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato" title="Class template stl_input_iterator">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code></a>
</h3></div></div></div>
<p>
Instances of <code class="computeroutput"><span class="identifier">stl_input_iterator</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> hold a Python iterator and adapt it
for use with STL algorithms. <code class="computeroutput"><span class="identifier">stl_input_iterator</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> satisfies the requirements for an Input
Iterator.
</p>
<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>
ValueType
</p>
</td>
<td>
<p>
ValueType must be CopyConstructible.
</p>
</td>
<td>
<p>
Dereferencing an instance of <code class="computeroutput"><span class="identifier">stl_input_iterator</span><span class="special">&lt;</span><span class="identifier">ValueType</span><span class="special">&gt;</span></code> will return an rvalue of
type ValueType.
</p>
</td>
<td>
<p>
None
</p>
</td>
</tr></tbody>
</table></div>
<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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ValueType</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">stl_input_iterator</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ptrdiff_t</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">ValueType</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">ValueType</span><span class="special">*</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">ValueType</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">input_iterator_tag</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="identifier">stl_input_iterator</span><span class="special">();</span>
<span class="identifier">stl_input_iterator</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">ob</span><span class="special">);</span>
<span class="identifier">stl_input_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="identifier">stl_input_iterator</span> <span class="keyword">operator</span><span class="special">++(</span><span class="keyword">int</span><span class="special">);</span>
<span class="identifier">ValueType</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!=(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">object</span> <span class="identifier">it</span><span class="special">;</span> <span class="comment">// For exposition only</span>
<span class="identifier">object</span> <span class="identifier">ob</span><span class="special">;</span> <span class="comment">// For exposition only</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0" title="Class template stl_input_iterator constructors">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code>
constructors</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">stl_input_iterator</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>
Creates a past-the-end input iterator, useful for signifying the
end of a sequence.
</p></dd>
<dt><span class="term">Postconditions</span></dt>
<dd><p>
<code class="computeroutput"><span class="keyword">this</span></code> is past-the-end
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
Nothing.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="identifier">stl_input_iterator</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">ob</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>
Calls ob.attr("__iter__")() and stores the resulting Python
iterator object in this-&gt;it. Then, calls this-&gt;it.attr("next")()
and stores the result in this-&gt;ob. If the sequence is exhausted,
sets this-&gt;ob to object().
</p></dd>
<dt><span class="term">Postconditions</span></dt>
<dd><p>
this is a dereferenceable or past-the-end.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1" title="Class template stl_input_iterator modifiers">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code>
modifiers</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">stl_input_iterator</span> <span class="special">&amp;</span><span class="keyword">operator</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>
Calls this-&gt;it.attr("next")() and stores the result
in this-&gt;ob. If the sequence is exhausted, sets this-&gt;ob to
object().
</p></dd>
<dt><span class="term">Postconditions</span></dt>
<dd><p>
this is a dereferenceable or past-the-end.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="identifier">stl_input_iterator</span> <span class="special">&amp;</span><span class="keyword">operator</span><span class="special">++(</span><span class="keyword">int</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>
<code class="computeroutput"><span class="identifier">stl_input_iterator</span> <span class="identifier">tmp</span> <span class="special">=</span>
<span class="special">*</span><span class="keyword">this</span><span class="special">;</span> <span class="special">++*</span><span class="keyword">this</span><span class="special">;</span> <span class="keyword">return</span> <span class="identifier">tmp</span><span class="special">;</span></code>
</p></dd>
<dt><span class="term">Postconditions</span></dt>
<dd><p>
this is a dereferenceable or past-the-end.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2" title="Class template stl_input_iterator observers">Class
template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code>
observers</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">ValueType</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span>
</pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Effects</span></dt>
<dd><p>
Returns the current element in the sequence.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">extract</span><span class="special">&lt;</span><span class="identifier">ValueType</span><span class="special">&gt;(</span><span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">ob</span><span class="special">);</span></code>
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</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>
Returns true if both iterators are dereferenceable or if both iterators
are past-the-end, false otherwise.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="special">(</span><span class="identifier">lhs</span><span class="special">.</span><span class="identifier">ob</span> <span class="special">==</span> <span class="identifier">object</span><span class="special">())</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">rhs</span><span class="special">.</span><span class="identifier">ob</span> <span class="special">==</span> <span class="identifier">object</span><span class="special">())</span></code>
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!=(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</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>
Returns false if both iterators are dereferenceable or if both iterators
are past-the-end, true otherwise.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="special">!(</span><span class="identifier">lhs</span>
<span class="special">==</span> <span class="identifier">rhs</span><span class="special">)</span></code>
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_stl_iterator_hpp.example"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">stl_iterator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">list</span><span class="special">&gt;</span>
<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="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">sequence_to_int_list</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">ob</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">stl_input_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">ob</span><span class="special">),</span> <span class="identifier">end</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">begin</span><span class="special">,</span> <span class="identifier">end</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_scope_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_wrapper_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,222 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/wrapper.hpp</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="../high_level_components.html" title="Chapter&#160;2.&#160;High Level Components">
<link rel="prev" href="boost_python_stl_iterator_hpp.html" title="boost/python/stl_iterator.hpp">
<link rel="next" href="../object_wrappers.html" title="Chapter&#160;3.&#160;Object Wrappers">
</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="boost_python_stl_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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="../object_wrappers.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="high_level_components.boost_python_wrapper_hpp"></a><a class="link" href="boost_python_wrapper_hpp.html" title="boost/python/wrapper.hpp">boost/python/wrapper.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override">Class
<code class="computeroutput"><span class="identifier">override</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override_observer_function">Class
<code class="computeroutput"><span class="identifier">override</span></code> observer functions</a></span></dt>
<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper">Class
template <code class="computeroutput"><span class="identifier">wrapper</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_">Class
template <code class="computeroutput"><span class="identifier">wrapper</span></code> observer
functions</a></span></dt>
<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_wrapper_hpp.introduction"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
To wrap a class T such that its virtual functions can be "overridden
in Python"&#8212;so that the corresponding method of a Python derived
class will be called when the virtual function is invoked from C++&#8212;you
must create a C++ wrapper class derived from <code class="computeroutput"><span class="identifier">T</span></code>
that overrides those virtual functions so that they call into Python. This
header contains classes that can be used to make that job easier.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_wrapper_hpp.class_override"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override" title="Class override">Class
<code class="computeroutput"><span class="identifier">override</span></code></a>
</h3></div></div></div>
<p>
Encapsulates a Python override of a C++ virtual function. An override object
either holds a callable Python object or <code class="computeroutput"><span class="identifier">None</span></code>.
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span>
<span class="special">{</span>
<span class="keyword">class</span> <span class="identifier">override</span> <span class="special">:</span> <span class="identifier">object</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="special">...</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="keyword">class</span> <span class="identifier">An</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="identifier">An</span><span class="special">)</span> <span class="keyword">const</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="high_level_components.boost_python_wrapper_hpp.class_override_observer_function"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override_observer_function" title="Class override observer functions">Class
<code class="computeroutput"><span class="identifier">override</span></code> observer functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="special">...</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="keyword">class</span> <span class="identifier">An</span><span class="special">&gt;</span>
<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="identifier">An</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>
If *this holds a callable Python object, it is invoked with the specified
arguments in the manner specified here. Otherwise, throws <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a>.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
An object of unspecified type that holds the Python result of the
invocation and, when converted to a C++ type R, attempts to convert
that result object to R. If that conversion fails, throws <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a>.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_wrapper_hpp.class_template_wrapper"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper" title="Class template wrapper">Class
template <code class="computeroutput"><span class="identifier">wrapper</span></code></a>
</h3></div></div></div>
<p>
Deriving your wrapper class from both <code class="computeroutput"><span class="identifier">T</span></code>
and <code class="computeroutput"><span class="identifier">wrapper</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
makes writing that derived class easier.
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span>
<span class="special">{</span>
<span class="keyword">class</span> <span class="identifier">wrapper</span>
<span class="special">{</span>
<span class="keyword">protected</span><span class="special">:</span>
<span class="identifier">override</span> <span class="identifier">get_override</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</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="high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_" title="Class template wrapper observer functions">Class
template <code class="computeroutput"><span class="identifier">wrapper</span></code> observer
functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">override</span> <span class="identifier">get_override</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</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">Requires</span></dt>
<dd><p>
name is a <a class="link" href="../glossary.html#ntbs">ntbs</a>.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
If <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
is the C++ base class subobject of a Python derived class instance
that overrides the named function, returns an override object that
delegates to the Python override. Otherwise, returns an override
object that holds <code class="computeroutput"><span class="identifier">None</span></code>.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="high_level_components.boost_python_wrapper_hpp.example"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">wrapper</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">call</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<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">// Class with one pure virtual function</span>
<span class="keyword">struct</span> <span class="identifier">P</span>
<span class="special">{</span>
<span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">P</span><span class="special">(){}</span>
<span class="keyword">virtual</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">g</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"P::g()"</span><span class="special">;</span> <span class="special">}</span>
<span class="special">};</span>
<span class="keyword">struct</span> <span class="identifier">PCallback</span> <span class="special">:</span> <span class="identifier">P</span><span class="special">,</span> <span class="identifier">wrapper</span><span class="special">&lt;</span><span class="identifier">P</span><span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">get_override</span><span class="special">(</span><span class="string">"f"</span><span class="special">)();</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="comment">// Class with one non-pure virtual function</span>
<span class="keyword">struct</span> <span class="identifier">A</span>
<span class="special">{</span>
<span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">A</span><span class="special">(){}</span>
<span class="keyword">virtual</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"A::f()"</span><span class="special">;</span> <span class="special">}</span>
<span class="special">};</span>
<span class="keyword">struct</span> <span class="identifier">ACallback</span> <span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">wrapper</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span>
<span class="special">{</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">override</span> <span class="identifier">f</span> <span class="special">=</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">get_override</span><span class="special">(</span><span class="string">"f"</span><span class="special">))</span>
<span class="keyword">return</span> <span class="identifier">f</span><span class="special">();</span>
<span class="keyword">return</span> <span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">();</span>
<span class="special">}</span>
<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">default_f</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">();</span> <span class="special">}</span>
<span class="special">};</span>
<span class="identifier">BOOST_PYTHON_MODULE_INIT</span><span class="special">(</span><span class="identifier">polymorphism</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">PCallback</span><span class="special">,</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span><span class="special">&gt;(</span><span class="string">"P"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">pure_virtual</span><span class="special">(&amp;</span><span class="identifier">P</span><span class="special">::</span><span class="identifier">f</span><span class="special">))</span>
<span class="special">;</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">ACallback</span><span class="special">,</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span><span class="special">&gt;(</span><span class="string">"A"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">ACallback</span><span class="special">::</span><span class="identifier">default_f</span><span class="special">)</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_stl_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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="../object_wrappers.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>