[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,96 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/call.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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="next" href="boost_python_call_method_hpp.html" title="boost/python/call_method.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="../function_invocation_and_creation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_call_method_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="function_invocation_and_creation.boost_python_call_hpp"></a><a class="link" href="boost_python_call_hpp.html" title="boost/python/call.hpp">boost/python/call.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.function_call">Function
<code class="computeroutput"><span class="identifier">call</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_call_hpp.introduction"></a><a class="link" href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<pre class="programlisting"><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="identifier">defines</span> <span class="identifier">the</span> <span class="identifier">call</span> <span class="identifier">family</span> <span class="identifier">of</span> <span class="identifier">overloaded</span> <span class="identifier">function</span> <span class="identifier">templates</span><span class="special">,</span> <span class="identifier">used</span> <span class="identifier">to</span> <span class="identifier">invoke</span> <span class="identifier">Python</span> <span class="identifier">callable</span> <span class="identifier">objects</span> <span class="identifier">from</span> <span class="identifier">C</span><span class="special">++.</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_call_hpp.function_call"></a><a class="link" href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.function_call" title="Function call">Function
<code class="computeroutput"><span class="identifier">call</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">R</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="special">...</span> <span class="keyword">class</span> <span class="identifier">An</span><span class="special">&gt;</span>
<span class="identifier">R</span> <span class="identifier">call</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">callable</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="special">...</span> <span class="identifier">An</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>
R is a pointer type, reference type, or a complete type with an accessible
copy constructor
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Invokes callable(a1, a2, ...an) in Python, where a1...an are the
arguments to call(), converted to Python objects.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
The result of the Python call, converted to the C++ type R.
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
For a complete semantic description and rationale, see this page.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_call_hpp.example"></a><a class="link" href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
The following C++ function applies a Python callable object to its two
arguments and returns the result. If a Python exception is raised or the
result can't be converted to a double, an exception is thrown.
</p>
<pre class="programlisting"><span class="keyword">double</span> <span class="identifier">apply2</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</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">call</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(</span><span class="identifier">func</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">}</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="../function_invocation_and_creation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_call_method_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,156 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/call_method.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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="boost_python_call_hpp.html" title="boost/python/call.hpp">
<link rel="next" href="boost_python_data_members_hpp.html" title="boost/python/data_members.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_call_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_data_members_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="function_invocation_and_creation.boost_python_call_method_hpp"></a><a class="link" href="boost_python_call_method_hpp.html" title="boost/python/call_method.hpp">boost/python/call_method.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.function_call_method">Function
<code class="computeroutput"><span class="identifier">call_method</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_call_method_hpp.introduction"></a><a class="link" href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
&lt;boost/python/call_method.hpp&gt; defines the call_method family of
overloaded function templates, used to invoke callable attributes of Python
objects from C++.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_call_method_hpp.function_call_method"></a><a class="link" href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.function_call_method" title="Function call_method">Function
<code class="computeroutput"><span class="identifier">call_method</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">R</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="special">...</span> <span class="keyword">class</span> <span class="identifier">An</span><span class="special">&gt;</span>
<span class="identifier">R</span> <span class="identifier">call_method</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">method</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="special">...</span> <span class="identifier">An</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>
<code class="computeroutput"><span class="identifier">R</span></code> is a pointer type,
reference type, or a complete type with an accessible copy constructor
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Invokes <code class="computeroutput"><span class="identifier">self</span><span class="special">.</span><span class="identifier">method</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> <span class="special">...</span><span class="identifier">an</span><span class="special">)</span></code> in Python, where <code class="computeroutput"><span class="identifier">a1</span><span class="special">...</span><span class="identifier">an</span></code>
are the arguments to <code class="computeroutput"><span class="identifier">call_method</span><span class="special">()</span></code>, converted to Python objects. For
a complete semantic description, see this page.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
The result of the Python call, converted to the C++ type <code class="computeroutput"><span class="identifier">R</span></code>.
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">call_method</span></code> is critical
to implementing C++ virtual functions which are overridable in Python,
as shown by the example below.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_call_method_hpp.example"></a><a class="link" href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
The following C++ illustrates the use of <code class="computeroutput"><span class="identifier">call_method</span></code>
in wrapping a class with a virtual function that can be overridden in Python:
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">utility</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">cstring</span><span class="special">&gt;</span>
<span class="comment">// class to be wrapped</span>
<span class="keyword">class</span> <span class="identifier">Base</span>
<span class="special">{</span>
<span class="keyword">public</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">class_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"Base"</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">Base</span><span class="special">();</span>
<span class="special">};</span>
<span class="keyword">bool</span> <span class="identifier">is_base</span><span class="special">(</span><span class="identifier">Base</span><span class="special">*</span> <span class="identifier">b</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="special">!</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">b</span><span class="special">-&gt;</span><span class="identifier">class_name</span><span class="special">(),</span> <span class="string">"Base"</span><span class="special">);</span>
<span class="special">}</span>
<span class="comment">// Wrapper code begins here</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">// Callback class</span>
<span class="keyword">class</span> <span class="identifier">Base_callback</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">Base</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">Base_callback</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_self</span><span class="special">(</span><span class="identifier">self</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">class_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">call_method</span><span class="special">&lt;</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*&gt;(</span><span class="identifier">m_self</span><span class="special">,</span> <span class="string">"class_name"</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">Base_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">Base</span><span class="special">::</span><span class="identifier">class_name</span><span class="special">();</span> <span class="special">}</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">const</span> <span class="identifier">m_self</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">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"is_base"</span><span class="special">,</span> <span class="identifier">is_base</span><span class="special">);</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Base</span><span class="special">,</span><span class="identifier">Base_callback</span><span class="special">,</span> <span class="identifier">noncopyable</span><span class="special">&gt;(</span><span class="string">"Base"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"class_name"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Base_callback</span><span class="special">::</span><span class="identifier">Base_name</span><span class="special">)</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">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="keyword">class</span> <span class="identifier">Derived</span><span class="special">(</span><span class="identifier">Base</span><span class="special">):</span>
<span class="special">...</span> <span class="identifier">def</span> <span class="identifier">__init__</span><span class="special">(</span><span class="identifier">self</span><span class="special">):</span>
<span class="special">...</span> <span class="identifier">Base</span><span class="special">.</span><span class="identifier">__init__</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span>
<span class="special">...</span> <span class="identifier">def</span> <span class="identifier">class_name</span><span class="special">(</span><span class="identifier">self</span><span class="special">):</span>
<span class="special">...</span> <span class="keyword">return</span> <span class="identifier">self</span><span class="special">.</span><span class="identifier">__class__</span><span class="special">.</span><span class="identifier">__name__</span>
<span class="special">...</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">is_base</span><span class="special">(</span><span class="identifier">Base</span><span class="special">())</span> <span class="special">#</span> <span class="identifier">calls</span> <span class="identifier">the</span> <span class="identifier">class_name</span><span class="special">()</span> <span class="identifier">method</span> <span class="identifier">from</span> <span class="identifier">C</span><span class="special">++</span>
<span class="number">1</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">is_base</span><span class="special">(</span><span class="identifier">Derived</span><span class="special">())</span>
<span class="number">0</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_call_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_data_members_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,215 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/data_members.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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="boost_python_call_method_hpp.html" title="boost/python/call_method.hpp">
<link rel="next" href="boost_python_make_function_hpp.html" title="boost/python/make_function.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_call_method_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_make_function_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="function_invocation_and_creation.boost_python_data_members_hpp"></a><a class="link" href="boost_python_data_members_hpp.html" title="boost/python/data_members.hpp">boost/python/data_members.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.functions">Functions</a></span></dt>
<dt><span class="section"><a href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_data_members_hpp.introduction"></a><a class="link" href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">make_getter</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">make_setter</span><span class="special">()</span></code>
are the functions used internally by <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"><code class="computeroutput"><span class="identifier">class_</span><span class="special">&lt;&gt;::</span><span class="identifier">def_readonly</span></code></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"><code class="computeroutput"><span class="identifier">class_</span><span class="special">&lt;&gt;::</span><span class="identifier">def_readwrite</span></code></a> to produce Python
callable objects which wrap C++ data members.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_data_members_hpp.functions"></a><a class="link" href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_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">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</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">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</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>
</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"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Creates a Python callable object which accepts a single argument
that can be converted from_python to C*, and returns the corresponding
member D member of the C object, converted to_python. If policies
is supplied, it will be applied to the function as described here.
Otherwise, the library attempts to determine whether D is a user-defined
class type, and if so uses return_internal_reference&lt;&gt; for
Policies. Note that this test may inappropriately choose return_internal_reference&lt;&gt;
in some cases when D is a smart pointer type. This is a known defect.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
An instance of object which holds the new Python callable object.
</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">D</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">d</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">d</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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">p</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">p</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>
</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 CallPolicies.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Creates a Python callable object which accepts no arguments and returns
d or *p, converted to_python on demand. If policies is supplied,
it will be applied to the function as described here. Otherwise,
the library attempts to determine whether D is a user-defined class
type, and if so uses reference_existing_object for Policies.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
An instance of object which holds the new Python callable object.
</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">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</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">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</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>
</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 CallPolicies.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Creates a Python callable object which, when called from Python,
expects two arguments which can be converted from_python to C* and
D const&amp;, respectively, and sets the corresponding D member of
the C object. If policies is supplied, it will be applied to the
function as described here.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
An instance of object which holds the new Python callable object.
</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">D</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">&amp;</span> <span class="identifier">d</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">&amp;</span> <span class="identifier">d</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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">*</span> <span class="identifier">p</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">*</span> <span class="identifier">p</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>
</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 CallPolicies.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Creates a Python callable object which accepts one argument, which
is converted from Python to D const&amp; and written into d or *p,
respectively. If policies is supplied, it will be applied to the
function as described here.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
An instance of object which holds the new Python callable object.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_data_members_hpp.example"></a><a class="link" href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
The code below uses make_getter and make_setter to expose a data member
as functions:
</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">data_members</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="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">X</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="special">:</span> <span class="identifier">y</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</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">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_INIT</span><span class="special">(</span><span class="identifier">data_members_example</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="identifier">init</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;())</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get"</span><span class="special">,</span> <span class="identifier">make_getter</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="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"set"</span><span class="special">,</span> <span class="identifier">make_setter</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="special">;</span>
<span class="special">}</span>
</pre>
<p>
It can be used this way in Python:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">data_members_example</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">X</span><span class="special">(</span><span class="number">1</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span>
<span class="number">1</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="number">2</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span>
<span class="number">2</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_call_method_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_make_function_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,194 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/make_function.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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="boost_python_data_members_hpp.html" title="boost/python/data_members.hpp">
<link rel="next" href="boost_python_overloads_hpp.html" title="boost/python/overloads.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_data_members_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_overloads_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="function_invocation_and_creation.boost_python_make_function_hpp"></a><a class="link" href="boost_python_make_function_hpp.html" title="boost/python/make_function.hpp">boost/python/make_function.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions">Functions</a></span></dt>
<dt><span class="section"><a href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_make_function_hpp.introduction"></a><a class="link" href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
make_function() and make_constructor() are the functions used internally
by def() and class_&lt;&gt;::def() to produce Python callable objects which
wrap C++ functions and member functions.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_make_function_hpp.functions"></a><a class="link" href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_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="identifier">object</span> <span class="identifier">make_function</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">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">KeywordsOrSignature</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</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="identifier">KeywordsOrSignature</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">ks</span><span class="special">)</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Signature</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</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="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">kw</span><span class="special">,</span> <span class="identifier">Signature</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">sig</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>
F is a function pointer or member function pointer type. If policies
are supplied, it must be a model of CallPolicies. If kewords are
supplied, it must be the result of a keyword-expression specifying
no more arguments than the arity of f.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd>
<p>
Creates a Python callable object which, when called from Python,
converts its arguments to C++ and calls f. If F is a pointer-to-member-function
type, the target object of the function call (*this) will be taken
from the first Python argument, and subsequent Python arguments will
be used as the arguments to f.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
If policies are supplied, it will be applied to the function
as described here.
</li>
<li class="listitem">
If keywords are supplied, the keywords will be applied in order
to the final arguments of the resulting function.
</li>
<li class="listitem">
If Signature is supplied, it should be an instance of an MPL
front-extensible sequence representing the function's return
type followed by its argument types. Pass a Signature when wrapping
function object types whose signatures can't be deduced, or when
you wish to override the types which will be passed to the wrapped
function.
</li>
</ul></div>
</dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
An instance of object which holds the new Python callable object.
</p></dd>
<dt><span class="term">Caveats</span></dt>
<dd><p>
An argument of pointer type may be 0 if None is passed from Python.
An argument type which is a constant reference may refer to a temporary
which was created from the Python object for just the duration of
the call to the wrapped function, for example a std::vector conjured
up by the conversion process from a Python list. Use a non-const
reference argument when a persistent lvalue is required.
</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">F</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_constructor</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">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_constructor</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">KeywordsOrSignature</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_constructor</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</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="identifier">KeywordsOrSignature</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">ks</span><span class="special">)</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Signature</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">make_constructor</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</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="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">kw</span><span class="special">,</span> <span class="identifier">Signature</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">sig</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>
F is a function pointer type. If policies are supplied, it must be
a model of CallPolicies. If kewords are supplied, it must be the
result of a keyword-expression specifying no more arguments than
the arity of f.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Creates a Python callable object which, when called from Python,
converts its arguments to C++ and calls f.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
An instance of object which holds the new Python callable object.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_make_function_hpp.example"></a><a class="link" href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
C++ function exposed below returns a callable object wrapping one of two
functions.
</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">make_function</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">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">foo</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="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">bar</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"bar"</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">object</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">selector</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">selector</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">make_function</span><span class="special">(</span><span class="identifier">foo</span><span class="special">);</span>
<span class="keyword">else</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">make_function</span><span class="special">(</span><span class="identifier">bar</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">make_function_test</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"choose_function"</span><span class="special">,</span> <span class="identifier">choose_function</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
It can be used this way in Python:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">make_function_test</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="number">1</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">g</span> <span class="special">=</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span><span class="special">()</span>
<span class="char">'foo'</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">g</span><span class="special">()</span>
<span class="char">'bar'</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_data_members_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_overloads_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/overloads.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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="boost_python_make_function_hpp.html" title="boost/python/make_function.hpp">
<link rel="next" href="boost_python_ptr_hpp.html" title="boost/python/ptr.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_make_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_ptr_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="function_invocation_and_creation.boost_python_overloads_hpp"></a><a class="link" href="boost_python_overloads_hpp.html" title="boost/python/overloads.hpp">boost/python/overloads.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept">OverloadDispatcher
Concept</a></span></dt>
<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros">Macros</a></span></dt>
<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_overloads_hpp.introduction"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions">overload-dispatch-expressions</a></span></dt></dl></div>
<p>
Defines facilities for generating families of overloaded Python functions
and extension class methods from C++ functions and member functions with
default arguments, or from similar families of C++ overloads
</p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">overload-dispatch-expressions</a>
</h4></div></div></div>
<p>
An overload-dispatch-expression is used to describe a family of overloaded
methods to be generated for an extension class. It 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
methods' <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 methods.
</p></dd>
<dt><span class="term">call policies</span></dt>
<dd><p>
An instance of some type which models CallPolicies.
</p></dd>
<dt><span class="term">minimum arity</span></dt>
<dd><p>
The minimum number of arguments to be accepted by a generated method
overload.
</p></dd>
<dt><span class="term">maximum arity</span></dt>
<dd><p>
The maximum number of arguments to be accepted by a generated method
overload.
</p></dd>
</dl>
</div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept" title="OverloadDispatcher Concept">OverloadDispatcher
Concept</a>
</h3></div></div></div>
<p>
An OverloadDispatcher X is a class which has a minimum arity and a maximum
arity, and for which the following following are valid overload-dispatch-expressions,
with the same minimum and maximum arity as the OverloadDispatcher.
</p>
<pre class="programlisting"><span class="identifier">X</span><span class="special">()</span>
<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">)</span>
<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">,</span> <span class="identifier">keywords</span><span class="special">)</span>
<span class="identifier">X</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">,</span> <span class="identifier">docstring</span><span class="special">)</span>
<span class="identifier">X</span><span class="special">()[</span><span class="identifier">policies</span><span class="special">]</span>
<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">)[</span><span class="identifier">policies</span><span class="special">]</span>
<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">,</span> <span class="identifier">keywords</span><span class="special">)[</span><span class="identifier">policies</span><span class="special">]</span>
<span class="identifier">X</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">,</span> <span class="identifier">docstring</span><span class="special">)[</span><span class="identifier">policies</span><span class="special">]</span>
</pre>
<p>
* If policies are supplied, it must be an instance of a type which models
<a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>, and will be
used as the result's call policies. Otherwise the result's call policies
will be an instance of <a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici" title="boost/python/default_call_policies.hpp"><code class="computeroutput"><span class="identifier">default_call_policies</span></code></a>. * If docstring
is supplied it must be an <a class="link" href="../glossary.html#ntbs">ntbs</a>, and will be
used as the result's docstring. Otherwise the result has an empty docstring.
* If keywords is supplied it must be 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>
whose length is no greater than X's maximum arity, and will be used as
the result's keywords. Otherwise the result's keywords will be empty.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_overloads_hpp.macros"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros" title="Macros">Macros</a>
</h3></div></div></div>
<pre class="programlisting"><span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">func_id</span><span class="special">,</span> <span class="identifier">min_args</span><span class="special">,</span> <span class="identifier">max_args</span><span class="special">)</span>
</pre>
<p>
Expands to the definition of an OverloadDispatcher called name in the current
scope which can be used to generate the following function invocation:
</p>
<pre class="programlisting"><span class="identifier">func_id</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">ai</span><span class="special">);</span></pre>
<p>
for all <code class="computeroutput"><span class="identifier">min_args</span> <span class="special">&lt;=</span>
<span class="identifier">i</span> <span class="special">&lt;=</span>
<span class="identifier">max_args</span></code>.
</p>
<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">member_name</span><span class="special">,</span> <span class="identifier">min_args</span><span class="special">,</span> <span class="identifier">max_args</span><span class="special">)</span>
</pre>
<p>
Expands to the definition of an OverloadDispatcher called name in the current
scope which can be used to generate the following function invocation:
</p>
<pre class="programlisting"><span class="identifier">x</span><span class="special">.</span><span class="identifier">member_name</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">ai</span><span class="special">);</span></pre>
<p>
for all min_args &lt;= i &lt;= max_args, where x is a reference to an object
of class type.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_overloads_hpp.example"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_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="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">tuple</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">overloads</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">return_internal_reference</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="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">make_tuple</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="identifier">z</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">f_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span>
<span class="keyword">struct</span> <span class="identifier">Y</span> <span class="special">{};</span>
<span class="keyword">struct</span> <span class="identifier">X</span>
<span class="special">{</span>
<span class="identifier">Y</span><span class="special">&amp;</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">inner</span><span class="special">;</span>
<span class="special">}</span>
<span class="identifier">Y</span> <span class="identifier">inner</span><span class="special">;</span>
<span class="special">};</span>
<span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">f_member_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">args_ext</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">f</span><span class="special">,</span>
<span class="identifier">f_overloads</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">"z"</span><span class="special">),</span> <span class="string">"This is f's docstring"</span>
<span class="special">));</span>
<span class="identifier">class_</span><span class="special">&lt;</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">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="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f1"</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="identifier">f_member_overloads</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">"z"</span><span class="special">),</span> <span class="string">"f's docstring"</span>
<span class="special">)[</span><span class="identifier">return_internal_reference</span><span class="special">&lt;&gt;()]</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_make_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_ptr_hpp.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,287 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/ptr.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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="boost_python_overloads_hpp.html" title="boost/python/overloads.hpp">
<link rel="next" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.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_overloads_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_raw_function_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="function_invocation_and_creation.boost_python_ptr_hpp"></a><a class="link" href="boost_python_ptr_hpp.html" title="boost/python/ptr.hpp">boost/python/ptr.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions">Functions</a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code>
types</a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code>
constructors and destructor</a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code>
observer functions</a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions">Metafunctions</a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.introduction"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
&lt;boost/python/ptr.hpp&gt; defines the ptr() function template, which
allows users to specify how to convert C++ pointer values to python in
the context of implementing overridable virtual functions, invoking Python
callable objects, or explicitly converting C++ objects to Python. Normally,
when passing pointers to Python callbacks, the pointee is copied to ensure
that the Python object never holds a dangling reference. To specify that
the new Python object should merely contain a copy of a pointer p, the
user can pass ptr(p) instead of passing p directly. This interface is meant
to mirror the use of boost::ref(), which can be similarly used to prevent
copying of referents.
</p>
<p>
ptr(p) returns an instance of <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper" title="Class template pointer_wrapper"><code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special">&lt;&gt;</span></code></a>,
which can be detected using the <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe" title="Class template is_pointer_wrapper"><code class="computeroutput"><span class="identifier">is_pointer_wrapper</span><span class="special">&lt;&gt;</span></code></a>
metafunction; <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer" title="Class template unwrap_pointer"><code class="computeroutput"><span class="identifier">unwrap_pointer</span><span class="special">&lt;&gt;</span></code></a>
is a metafunction which extracts the original pointer type from a <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special">&lt;&gt;</span></code>.
These classes can be thought of as implementation details.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.functions"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_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="identifier">pointer_wrapper</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">ptr</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>
T is a pointer type.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
pointer_wrapper&lt;T&gt;(x)
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
nothing.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper" title="Class template pointer_wrapper">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a>
</h3></div></div></div>
<p>
A "type envelope" which is returned by <code class="computeroutput"><span class="identifier">ptr</span><span class="special">()</span></code>, used to indicate reference semantics
for pointers passed to Python callbacks.
</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">Ptr</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">pointer_wrapper</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">Ptr</span> <span class="identifier">type</span><span class="special">;</span>
<span class="keyword">explicit</span> <span class="identifier">pointer_wrapper</span><span class="special">(</span><span class="identifier">Ptr</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">operator</span> <span class="identifier">Ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">Ptr</span> <span class="identifier">get</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="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t" title="Class template pointer_wrapper types">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code>
types</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">Ptr</span> <span class="identifier">type</span><span class="special">;</span>
</pre>
<p>
The type of the pointer being wrapped.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c" title="Class template pointer_wrapper constructors and destructor">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code>
constructors and destructor</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">pointer_wrapper</span><span class="special">(</span><span class="identifier">Ptr</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>
<code class="computeroutput"><span class="identifier">Ptr</span></code> is a pointer
type
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Stores <code class="computeroutput"><span class="identifier">x</span></code> in a the
<code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special">&lt;&gt;</span></code>.
</p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
nothing.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o" title="Class template pointer_wrapper observer functions">Class
template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code>
observer functions</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">operator</span> <span class="identifier">Ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">Ptr</span> <span class="identifier">get</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">Returns</span></dt>
<dd><p>
a copy of the stored pointer.
</p></dd>
<dt><span class="term">Rationale</span></dt>
<dd><p>
pointer_wrapper is intended to be a stand-in for the actual pointer
type, but sometimes it's better to have an explicit way to retrieve
the pointer.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions" title="Metafunctions">Metafunctions</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe">Class
template <code class="computeroutput"><span class="identifier">is_pointer_wrapper</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer">Class
template <code class="computeroutput"><span class="identifier">unwrap_pointer</span></code></a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe" title="Class template is_pointer_wrapper">Class
template <code class="computeroutput"><span class="identifier">is_pointer_wrapper</span></code></a>
</h4></div></div></div>
<p>
A unary metafunction whose value is true iff its argument is a pointer_wrapper&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="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">is_pointer_wrapper</span>
<span class="special">{</span>
<span class="keyword">static</span> <span class="identifier">unspecified</span> <span class="identifier">value</span> <span class="special">=</span> <span class="special">...;</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">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="keyword">true</span></code> iff <code class="computeroutput"><span class="identifier">T</span></code> is a specialization of <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special">&lt;&gt;</span></code>.
value is an integral constant convertible to bool of unspecified
type
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer" title="Class template unwrap_pointer">Class
template <code class="computeroutput"><span class="identifier">unwrap_pointer</span></code></a>
</h4></div></div></div>
<p>
A unary metafunction which extracts the wrapped pointer type from a specialization
of pointer_wrapper&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="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">unwrap_pointer</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">unspecified</span> <span class="identifier">type</span><span class="special">;</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">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">type</span></code> if <code class="computeroutput"><span class="identifier">T</span></code>
is a specialization of <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special">&lt;&gt;</span></code>, <code class="computeroutput"><span class="identifier">T</span></code>
otherwise
</p></dd>
</dl>
</div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_ptr_hpp.example"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
This example illustrates the use of ptr() to prevent an object from being
copied:
</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">call</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">ptr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">expensive_to_copy</span>
<span class="special">{</span>
<span class="special">...</span>
<span class="special">};</span>
<span class="keyword">void</span> <span class="identifier">pass_as_arg</span><span class="special">(</span><span class="identifier">expensive_to_copy</span><span class="special">*</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">f</span><span class="special">)</span>
<span class="special">{</span>
<span class="comment">// call the Python function f, passing a Python object built around</span>
<span class="comment">// which refers to *x by-pointer.</span>
<span class="comment">//</span>
<span class="comment">// *** Note: ensuring that *x outlives the argument to f() is ***</span>
<span class="comment">// *** up to the user! Failure to do so could result in a crash! ***</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">&lt;</span><span class="keyword">void</span><span class="special">&gt;(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">ptr</span><span class="special">(</span><span class="identifier">x</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_overloads_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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_raw_function_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/raw_function.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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="boost_python_ptr_hpp.html" title="boost/python/ptr.hpp">
<link rel="next" href="function_documentation.html" title="Function documentation">
</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_ptr_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="function_documentation.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="function_invocation_and_creation.boost_python_raw_function_hpp"></a><a class="link" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.hpp">boost/python/raw_function.hpp</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function">Function
<code class="computeroutput"><span class="identifier">raw_function</span></code></a></span></dt>
<dt><span class="section"><a href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_raw_function_hpp.introduction"></a><a class="link" href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.introduction" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">raw_function</span><span class="special">(...)</span></code>
is used to convert a function taking a <a class="link" href="../object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.class_tuple" title="Class tuple"><code class="computeroutput"><span class="identifier">tuple</span></code></a> and a <a class="link" href="../object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict" title="Class dict"><code class="computeroutput"><span class="identifier">dict</span></code></a> into a Python callable object
which accepts a variable number of arguments and arbitrary keyword arguments.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function"></a><a class="link" href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function" title="Function raw_function">Function
<code class="computeroutput"><span class="identifier">raw_function</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">F</span><span class="special">&gt;</span>
<span class="identifier">object</span> <span class="identifier">raw_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">min_args</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>
f(tuple(), dict()) is well-formed.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
a callable object which requires at least min_args arguments. When
called, the actual non-keyword arguments will be passed in a tuple
as the first argument to f, and the keyword arguments will be passed
in a dict as the second argument to f.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.boost_python_raw_function_hpp.example"></a><a class="link" href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.example" title="Example">Example</a>
</h3></div></div></div>
<p>
C++:
</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">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">tuple</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">dict</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">raw_function</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="identifier">tuple</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kw</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="identifier">kw</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">raw_test</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"raw"</span><span class="special">,</span> <span class="identifier">raw_function</span><span class="special">(</span><span class="identifier">raw</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
Python:
</p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">raw_test</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">raw</span><span class="special">(</span><span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="identifier">foo</span> <span class="special">=</span> <span class="char">'bar'</span><span class="special">,</span> <span class="identifier">baz</span> <span class="special">=</span> <span class="number">42</span><span class="special">)</span>
<span class="special">((</span><span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">),</span> <span class="special">{</span><span class="char">'foo'</span><span class="special">:</span> <span class="char">'bar'</span><span class="special">,</span> <span class="char">'baz'</span><span class="special">:</span> <span class="number">42</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_ptr_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="function_documentation.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,458 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Function documentation</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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.hpp">
<link rel="next" href="models_of_callpolicies.html" title="Models of CallPolicies">
</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_raw_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="models_of_callpolicies.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="function_invocation_and_creation.function_documentation"></a><a class="link" href="function_documentation.html" title="Function documentation">Function
documentation</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat">boost/python/function_doc_signature.hpp</a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp">boost/python/pytype_function.hpp</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat" title="boost/python/function_doc_signature.hpp">boost/python/function_doc_signature.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen">Class
<code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code></a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<p>
Boost.Python supports docstrings with automatic appending of Pythonic
and C++ signatures. This feature is implemented by class <code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code>. The
class uses all of the overloads, supplied arg names and default values,
as well as the user-defined docstrings, to generate documentation for
a given function.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen" title="Class function_doc_signature_generator">Class
<code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code></a>
</h4></div></div></div>
<p>
The class has only one public function which returns a list of strings
documenting the overloads of a 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">namespace</span> <span class="identifier">objects</span> <span class="special">{</span>
<span class="keyword">class</span> <span class="identifier">function_doc_signature_generator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">static</span> <span class="identifier">list</span> <span class="identifier">function_doc_signatures</span><span class="special">(</span><span class="identifier">function</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="special">}}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example" title="Example">Example</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">tuple</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">overloads</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">raw_function</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="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">make_tuple</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="identifier">z</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">f_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span>
<span class="keyword">struct</span> <span class="identifier">X</span>
<span class="special">{</span>
<span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">make_tuple</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="identifier">z</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">X_f_overloads</span><span class="special">,</span> <span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span>
<span class="identifier">tuple</span> <span class="identifier">raw_func</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kw</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="identifier">kw</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">args_ext</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">f</span><span class="special">,</span> <span class="special">(</span><span class="identifier">arg</span><span class="special">(</span><span class="string">"x"</span><span class="special">)=</span><span class="number">1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"y"</span><span class="special">)=</span><span class="number">4.25</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"z"</span><span class="special">)=</span><span class="string">"wow"</span><span class="special">)</span>
<span class="special">,</span> <span class="string">"This is f's docstring"</span>
<span class="special">);</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"raw"</span><span class="special">,</span> <span class="identifier">raw_function</span><span class="special">(</span><span class="identifier">raw_func</span><span class="special">));</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"f1"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">f_overloads</span><span class="special">(</span><span class="string">"f1's docstring"</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">"z"</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;&gt;(</span><span class="identifier">args</span><span class="special">(</span><span class="string">"self"</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="string">"This is X.f's docstring"</span>
<span class="special">,</span> <span class="identifier">args</span><span class="special">(</span><span class="string">"self"</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">"z"</span><span class="special">))</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="keyword">import</span> <span class="identifier">args_ext</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">help</span><span class="special">(</span><span class="identifier">args_ext</span><span class="special">)</span>
<span class="identifier">Help</span> <span class="identifier">on</span> <span class="identifier">module</span> <span class="identifier">args_ext</span><span class="special">:</span>
<span class="identifier">NAME</span>
<span class="identifier">args_ext</span>
<span class="identifier">FILE</span>
<span class="identifier">args_ext</span><span class="special">.</span><span class="identifier">pyd</span>
<span class="identifier">CLASSES</span>
<span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span><span class="special">.</span><span class="identifier">instance</span><span class="special">(</span><span class="identifier">__builtin__</span><span class="special">.</span><span class="identifier">object</span><span class="special">)</span>
<span class="identifier">X</span>
<span class="keyword">class</span> <span class="identifier">X</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">instance</span><span class="special">)</span>
<span class="special">|</span> <span class="identifier">This</span> <span class="keyword">is</span> <span class="identifier">X</span><span class="string">'s docstring
|
| Method resolution order:
| X
| Boost.Python.instance
| __builtin__.object
|
| Methods defined here:
|
| __init__(...)
| __init__( (object)self) -&gt; None :
| C++ signature:
| void __init__(struct _object *)
|
| f(...)
| f( (X)self, (int)x, (float)y, (str)z) -&gt; tuple : This is X.f'</span><span class="identifier">s</span> <span class="identifier">docstring</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="special">|</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">struct</span> <span class="identifier">X</span> <span class="special">{</span><span class="identifier">lvalue</span><span class="special">},</span><span class="identifier">int</span><span class="special">,</span><span class="identifier">double</span><span class="special">,</span><span class="identifier">char</span> <span class="identifier">const</span> <span class="special">*)</span>
<span class="special">|</span>
<span class="special">|</span> <span class="special">.................</span>
<span class="special">|</span>
<span class="identifier">FUNCTIONS</span>
<span class="identifier">f</span><span class="special">(...)</span>
<span class="identifier">f</span><span class="special">([</span> <span class="special">(</span><span class="identifier">int</span><span class="special">)</span><span class="identifier">x</span><span class="special">=</span><span class="number">1</span> <span class="special">[,</span> <span class="special">(</span><span class="identifier">float</span><span class="special">)</span><span class="identifier">y</span><span class="special">=</span><span class="number">4.25</span> <span class="special">[,</span> <span class="special">(</span><span class="identifier">str</span><span class="special">)</span><span class="identifier">z</span><span class="special">=</span><span class="string">'wow'</span><span class="special">]]])</span> <span class="special">-&gt;</span> <span class="identifier">tuple</span> <span class="special">:</span> <span class="identifier">This</span> <span class="keyword">is</span> <span class="identifier">f</span><span class="string">'s docstring
C++ signature:
class boost::python::tuple f([ int=1 [,double=4.25 [,char const *='</span><span class="identifier">wow</span><span class="string">']]])
f1(...)
f1([ (int)x [, (float)y [, (str)z]]]) -&gt; tuple : f1'</span><span class="identifier">s</span> <span class="identifier">docstring</span>
<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span>
<span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> <span class="identifier">f1</span><span class="special">([</span> <span class="identifier">int</span> <span class="special">[,</span><span class="identifier">double</span> <span class="special">[,</span><span class="identifier">char</span> <span class="identifier">const</span> <span class="special">*]]])</span>
<span class="identifier">raw</span><span class="special">(...)</span>
<span class="identifier">object</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kwds</span><span class="special">)</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">object</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kwds</span><span class="special">)</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp" title="boost/python/pytype_function.hpp">boost/python/pytype_function.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype">Class
<code class="computeroutput"><span class="identifier">wrap_pytype</span></code></a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype">Class
<code class="computeroutput"><span class="identifier">registered_pytype</span></code></a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type">Class
<code class="computeroutput"><span class="identifier">expected_from_python_type</span></code></a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type">Class
<code class="computeroutput"><span class="identifier">to_python_target_type</span></code></a></span></dt>
<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<p>
To support Pythonic signatures the converters should supply a <code class="computeroutput"><span class="identifier">get_pytype</span></code> function returning a pointer
to the associated <code class="computeroutput"><span class="identifier">PyTypeObject</span></code>.
See for example <a class="link" href="../concepts/resultconverter.html" title="ResultConverter"><code class="computeroutput"><span class="identifier">ResultConverter</span></code></a> or <a class="link" href="../to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert.class_template_to_python_convert" title="Class template to_python_converter constructor"><code class="computeroutput"><span class="identifier">to_python_converter</span></code></a>. The classes
in this header file are meant to be used when implmenting <code class="computeroutput"><span class="identifier">get_pytype</span></code>. There are also <code class="computeroutput"><span class="identifier">_direct</span></code> versions of the templates of
<code class="computeroutput"><span class="keyword">class</span> <span class="identifier">T</span></code>
which should be used with undecorated type parameter, expected to be
in the conversion registry when the module loads.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype" title="Class wrap_pytype">Class
<code class="computeroutput"><span class="identifier">wrap_pytype</span></code></a>
</h4></div></div></div>
<p>
This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code>
member returning the template 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">namespace</span> <span class="identifier">converter</span><span class="special">{</span>
<span class="keyword">template</span> <span class="special">&lt;</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">pytype</span> <span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">wrap_pytype</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">(){</span><span class="keyword">return</span> <span class="identifier">pytype</span><span class="special">;</span> <span class="special">}</span>
<span class="special">};</span>
<span class="special">}}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype" title="Class registered_pytype">Class
<code class="computeroutput"><span class="identifier">registered_pytype</span></code></a>
</h4></div></div></div>
<p>
This template should be used with template parameters which are (possibly
decorated) types exported to python using <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;"><code class="computeroutput"><span class="identifier">class_</span></code></a>. The generated a static
<code class="computeroutput"><span class="identifier">get_pytype</span></code> member returns
the corresponding python type.
</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">namespace</span> <span class="identifier">converter</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">registered_pytype</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span>
<span class="special">};</span>
<span class="special">}}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type" title="Class expected_from_python_type">Class
<code class="computeroutput"><span class="identifier">expected_from_python_type</span></code></a>
</h4></div></div></div>
<p>
This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code>
member which inspects the registered <code class="computeroutput"><span class="identifier">from_python</span></code>
converters for the type <code class="computeroutput"><span class="identifier">T</span></code>
and returns a matching python type.
</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">namespace</span> <span class="identifier">converter</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">expected_from_python_type</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span>
<span class="special">};</span>
<span class="special">}}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type" title="Class to_python_target_type">Class
<code class="computeroutput"><span class="identifier">to_python_target_type</span></code></a>
</h4></div></div></div>
<p>
This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code>
member returning the python type to which <code class="computeroutput"><span class="identifier">T</span></code>
can be converted.
</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">namespace</span> <span class="identifier">converter</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">to_python_target_type</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span>
<span class="special">};</span>
<span class="special">}}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example" title="Example">Example</a>
</h4></div></div></div>
<p>
This example presumes that someone has implemented the standard noddy
example module from the Python documentation, and placed the corresponding
declarations in "noddy.h". Because <code class="computeroutput"><span class="identifier">noddy_NoddyObject</span></code>
is the ultimate trivial extension type, the example is a bit contrived:
it wraps a function for which all information is contained in the type
of its return value.
</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">reference</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="string">"noddy.h"</span>
<span class="keyword">struct</span> <span class="identifier">tag</span> <span class="special">{};</span>
<span class="identifier">tag</span> <span class="identifier">make_tag</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">tag</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">struct</span> <span class="identifier">tag_to_noddy</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//unnecessary overhead if py signatures are not supported</span>
<span class="special">:</span> <span class="identifier">wrap_pytype</span><span class="special">&lt;&amp;</span><span class="identifier">noddy_NoddyType</span><span class="special">&gt;</span> <span class="comment">//inherits get_pytype from wrap_pytype</span>
<span class="preprocessor">#endif</span>
<span class="special">{</span>
<span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">tag</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">PyObject_New</span><span class="special">(</span><span class="identifier">noddy_NoddyObject</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">noddy_NoddyType</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">to_python_converter</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"make_tag"</span><span class="special">,</span> <span class="identifier">make_tag</span><span class="special">);</span>
<span class="identifier">to_python_converter</span><span class="special">&lt;</span><span class="identifier">tag</span><span class="special">,</span> <span class="identifier">tag_to_noddy</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span>
<span class="special">,</span> <span class="keyword">true</span>
<span class="preprocessor">#endif</span>
<span class="special">&gt;();</span> <span class="comment">//"true" because tag_to_noddy has member get_pytype</span>
<span class="special">}</span>
</pre>
<p>
The following example registers to and from python converters using the
templates expected_from_python_type and to_pyhton_target_type.
</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="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">extract</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">to_python_converter</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="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">A</span>
<span class="special">{</span>
<span class="special">};</span>
<span class="keyword">struct</span> <span class="identifier">B</span>
<span class="special">{</span>
<span class="identifier">A</span> <span class="identifier">a</span><span class="special">;</span>
<span class="identifier">B</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;</span> <span class="identifier">a_</span><span class="special">):</span><span class="identifier">a</span><span class="special">(</span><span class="identifier">a_</span><span class="special">){}</span>
<span class="special">};</span>
<span class="comment">// Converter from A to python int</span>
<span class="keyword">struct</span> <span class="identifier">BToPython</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//unnecessary overhead if py signatures are not supported</span>
<span class="special">:</span> <span class="identifier">converter</span><span class="special">::</span><span class="identifier">to_python_target_type</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span> <span class="comment">//inherits get_pytype</span>
<span class="preprocessor">#endif</span>
<span class="special">{</span>
<span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">incref</span><span class="special">(</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">b</span><span class="special">.</span><span class="identifier">a</span><span class="special">).</span><span class="identifier">ptr</span><span class="special">());</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="comment">// Conversion from python int to A</span>
<span class="keyword">struct</span> <span class="identifier">BFromPython</span>
<span class="special">{</span>
<span class="identifier">BFromPython</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">converter</span><span class="special">::</span><span class="identifier">registry</span><span class="special">::</span><span class="identifier">push_back</span>
<span class="special">(</span> <span class="special">&amp;</span><span class="identifier">convertible</span>
<span class="special">,</span> <span class="special">&amp;</span><span class="identifier">construct</span>
<span class="special">,</span> <span class="identifier">type_id</span><span class="special">&lt;</span> <span class="identifier">B</span> <span class="special">&gt;()</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span>
<span class="special">,</span> <span class="special">&amp;</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">expected_from_python_type</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;::</span><span class="identifier">get_pytype</span><span class="comment">//convertible to A can be converted to B</span>
<span class="preprocessor">#endif</span>
<span class="special">);</span>
<span class="special">}</span>
<span class="keyword">static</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">convertible</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">extract</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;&gt;</span> <span class="identifier">ex</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">);</span>
<span class="keyword">if</span> <span class="special">(!</span><span class="identifier">ex</span><span class="special">.</span><span class="identifier">check</span><span class="special">())</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">obj_ptr</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">construct</span><span class="special">(</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">,</span>
<span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_stage1_data</span><span class="special">*</span> <span class="identifier">data</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">void</span><span class="special">*</span> <span class="identifier">storage</span> <span class="special">=</span> <span class="special">(</span>
<span class="special">(</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_storage</span><span class="special">&lt;</span> <span class="identifier">B</span> <span class="special">&gt;*)</span><span class="identifier">data</span><span class="special">)-&gt;</span> <span class="identifier">storage</span><span class="special">.</span><span class="identifier">bytes</span><span class="special">;</span>
<span class="identifier">extract</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;&gt;</span> <span class="identifier">ex</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">);</span>
<span class="keyword">new</span> <span class="special">(</span><span class="identifier">storage</span><span class="special">)</span> <span class="identifier">B</span><span class="special">(</span><span class="identifier">ex</span><span class="special">());</span>
<span class="identifier">data</span><span class="special">-&gt;</span><span class="identifier">convertible</span> <span class="special">=</span> <span class="identifier">storage</span><span class="special">;</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="identifier">B</span> <span class="identifier">func</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span> <span class="special">;</span> <span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">pytype_function_ext</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">to_python_converter</span><span class="special">&lt;</span> <span class="identifier">B</span> <span class="special">,</span> <span class="identifier">BToPython</span>
<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span>
<span class="special">,</span><span class="keyword">true</span>
<span class="preprocessor">#endif</span>
<span class="special">&gt;();</span> <span class="comment">//has get_pytype</span>
<span class="identifier">BFromPython</span><span class="special">();</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">A</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">"func"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">func</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">pytype_function_ext</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">print</span> <span class="identifier">func</span><span class="special">.</span><span class="identifier">__doc__</span>
<span class="identifier">func</span><span class="special">(</span> <span class="special">(</span><span class="identifier">A</span><span class="special">)</span><span class="identifier">arg1</span><span class="special">)</span> <span class="special">-&gt;</span> <span class="identifier">A</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="keyword">struct</span> <span class="identifier">B</span> <span class="identifier">func</span><span class="special">(</span><span class="keyword">struct</span> <span class="identifier">B</span><span class="special">)</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_raw_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="models_of_callpolicies.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,308 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Models of ResultConverter</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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="models_of_callpolicies.html" title="Models of CallPolicies">
<link rel="next" href="models_of_resultconvertergenerat.html" title="Models of ResultConverterGenerator">
</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="models_of_callpolicies.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="models_of_resultconvertergenerat.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="function_invocation_and_creation.models_of_resultconverter"></a><a class="link" href="models_of_resultconverter.html" title="Models of ResultConverter">Models
of ResultConverter</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_">boost/python/to_python_indirect.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp">boost/python/to_python_value.hpp</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_" title="boost/python/to_python_indirect.hpp">boost/python/to_python_indirect.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect">Class
<code class="computeroutput"><span class="identifier">to_python_indirect</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_observe">Class
<code class="computeroutput"><span class="identifier">to_python_indirect</span></code> observers</a></span></dt>
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_statics">Class
<code class="computeroutput"><span class="identifier">to_python_indirect</span></code> statics</a></span></dt>
</dl></div>
<pre class="programlisting"><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">to_python_indirect</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="identifier">supplies</span> <span class="identifier">a</span> <span class="identifier">way</span> <span class="identifier">to</span> <span class="identifier">construct</span> <span class="keyword">new</span> <span class="identifier">Python</span> <span class="identifier">objects</span> <span class="identifier">that</span> <span class="identifier">hold</span> <span class="identifier">wrapped</span> <span class="identifier">C</span><span class="special">++</span> <span class="keyword">class</span> <span class="identifier">instances</span> <span class="identifier">via</span> <span class="identifier">a</span> <span class="identifier">pointer</span> <span class="keyword">or</span> <span class="identifier">smart</span> <span class="identifier">pointer</span><span class="special">.</span>
<span class="special">[</span><span class="identifier">endsect</span><span class="special">]</span>
</pre>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect" title="Class to_python_indirect">Class
<code class="computeroutput"><span class="identifier">to_python_indirect</span></code></a>
</h5></div></div></div>
<p>
Class template <code class="computeroutput"><span class="identifier">to_python_indirect</span></code>
converts objects of its first argument type to python as extension
class instances, using the ownership policy provided by its 2nd argument.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Parameter
</p>
</th>
<th>
<p>
Requirements
</p>
</th>
<th>
<p>
Description
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
T
</p>
</td>
<td>
<p>
Either <code class="computeroutput"><span class="identifier">U</span> <span class="identifier">cv</span><span class="special">&amp;</span></code>
(where cv is any optional cv-qualification) or a <a class="link" href="../concepts/dereferenceable.html" title="Dereferenceable">Dereferenceable</a>
type such that <code class="computeroutput"><span class="special">*</span><span class="identifier">x</span></code> is convertible to <code class="computeroutput"><span class="identifier">U</span> <span class="keyword">const</span><span class="special">&amp;</span></code>, where <code class="computeroutput"><span class="identifier">U</span></code> is a class type.
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">A</span></code> type deferencing
a C++ class exposed to Python using class template <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;"><code class="computeroutput"><span class="identifier">class_</span></code></a>.
</p>
</td>
</tr>
<tr>
<td>
<p>
MakeHolder
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">h</span> <span class="special">=</span>
<span class="identifier">MakeHolder</span><span class="special">::</span><span class="identifier">execute</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span></code>
</p>
</td>
<td>
<p>
A class whose static <code class="computeroutput"><span class="identifier">execute</span><span class="special">()</span></code> creates an <code class="computeroutput"><span class="identifier">instance_holder</span></code>.
</p>
</td>
</tr>
</tbody>
</table></div>
<p>
Instantiations of to_python_indirect are models of <a class="link" href="../concepts/resultconverter.html" title="ResultConverter"><code class="computeroutput"><span class="identifier">ResultConverter</span></code></a>.
</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">,</span> <span class="keyword">class</span> <span class="identifier">MakeHolder</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">to_python_indirect</span>
<span class="special">{</span>
<span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">convertible</span><span class="special">();</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="identifier">ptr_or_reference</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="keyword">static</span> <span class="identifier">PyTypeObject</span><span class="special">*</span> <span class="identifier">type</span><span class="special">();</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_observe"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_observe" title="Class to_python_indirect observers">Class
<code class="computeroutput"><span class="identifier">to_python_indirect</span></code> observers</a>
</h5></div></div></div>
<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="identifier">x</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>
<code class="computeroutput"><span class="identifier">x</span></code> refers to an
object (if it is a pointer type, it is non-null). <code class="computeroutput"><span class="identifier">convertible</span><span class="special">()</span>
<span class="special">==</span> <span class="keyword">true</span></code>.
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
Creates an appropriately-typed Boost.Python extension class instance,
uses MakeHolder to create an instance_holder from x, installs
the instance_holder in the new extension class instance, and
returns a pointer to it.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_statics"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_statics" title="Class to_python_indirect statics">Class
<code class="computeroutput"><span class="identifier">to_python_indirect</span></code> statics</a>
</h5></div></div></div>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">convertible</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 iff any module has registered a Python type corresponding
to U.
</p></dd>
</dl>
</div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.example"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.example" title="Example">Example</a>
</h4></div></div></div>
<p>
This example replicates the functionality of <a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object" title="Class reference_existing_object"><code class="computeroutput"><span class="identifier">reference_existing_object</span></code></a>, but
without some of the compile-time error checking.
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">make_reference_holder</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">objects</span><span class="special">::</span><span class="identifier">instance_holder</span><span class="special">*</span> <span class="identifier">result_type</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">static</span> <span class="identifier">result_type</span> <span class="identifier">execute</span><span class="special">(</span><span class="identifier">T</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="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">objects</span><span class="special">::</span><span class="identifier">pointer_holder</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">*,</span> <span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">p</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="keyword">struct</span> <span class="identifier">reference_existing_object</span>
<span class="special">{</span>
<span class="comment">// metafunction returning the ResultConverter</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">struct</span> <span class="identifier">apply</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">to_python_indirect</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">make_reference_holder</span><span class="special">&gt;</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">};</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp" title="boost/python/to_python_value.hpp">boost/python/to_python_value.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_template_to_python_value">Class
template <code class="computeroutput"><span class="identifier">to_python_value</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_to_python_value_observers">Class
<code class="computeroutput"><span class="identifier">to_python_value</span></code> observers</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.introduction"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">to_python_value</span></code> is a
model of <a class="link" href="../concepts/resultconverter.html" title="ResultConverter">ResultConverter</a>
which copies its argument into a new Python object.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_template_to_python_value"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_template_to_python_value" title="Class template to_python_value">Class
template <code class="computeroutput"><span class="identifier">to_python_value</span></code></a>
</h4></div></div></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">T</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">to_python_value</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">add_reference</span><span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">add_const</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span>
<span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">argument_type</span><span class="special">;</span>
<span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">convertible</span><span class="special">();</span>
<span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">argument_type</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><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_to_python_value_observers"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_to_python_value_observers" title="Class to_python_value observers">Class
<code class="computeroutput"><span class="identifier">to_python_value</span></code> observers</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">convertible</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>
<code class="computeroutput"><span class="keyword">true</span></code> iff a converter
has been registered which can convert <code class="computeroutput"><span class="identifier">T</span></code>
to python by-value.
</p></dd>
</dl>
</div>
<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">argument_type</span> <span class="identifier">x</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>
<code class="computeroutput"><span class="identifier">convertible</span><span class="special">()</span>
<span class="special">==</span> <span class="keyword">true</span></code>
</p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
converts <code class="computeroutput"><span class="identifier">x</span></code> to python
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
the resulting Python object iff a converter for <code class="computeroutput"><span class="identifier">T</span></code>
has been registered, <code class="computeroutput"><span class="number">0</span></code>
otherwise.
</p></dd>
</dl>
</div>
</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="models_of_callpolicies.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="models_of_resultconvertergenerat.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,683 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Models of ResultConverterGenerator</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="../function_invocation_and_creation.html" title="Chapter&#160;4.&#160;Function Invocation and Creation">
<link rel="prev" href="models_of_resultconverter.html" title="Models of ResultConverter">
<link rel="next" href="../to_from_python_type_conversion.html" title="Chapter&#160;5.&#160;To/From Python Type Conversion">
</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="models_of_resultconverter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="../to_from_python_type_conversion.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="function_invocation_and_creation.models_of_resultconvertergenerat"></a><a class="link" href="models_of_resultconvertergenerat.html" title="Models of ResultConverterGenerator">Models
of ResultConverterGenerator</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc">boost/python/copy_const_reference.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe">boost/python/copy_non_const_reference.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h">boost/python/manage_new_object.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_">boost/python/reference_existing_object.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp">boost/python/return_by_value.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point">boost/python/return_opaque_pointer.hpp</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc" title="boost/python/copy_const_reference.hpp">boost/python/copy_const_reference.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference">Class
<code class="computeroutput"><span class="identifier">copy_const_reference</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference_metaf">Class
<code class="computeroutput"><span class="identifier">copy_const_reference</span></code> metafunctions</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference" title="Class copy_const_reference">Class
<code class="computeroutput"><span class="identifier">copy_const_reference</span></code></a>
</h4></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">copy_const_reference</span></code>
is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a>
which can be used to wrap C++ functions returning a reference-to-const
type such that the referenced value is copied into a new Python object.
</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">struct</span> <span class="identifier">copy_const_reference</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">struct</span> <span class="identifier">apply</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference_metaf"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference_metaf" title="Class copy_const_reference metafunctions">Class
<code class="computeroutput"><span class="identifier">copy_const_reference</span></code> metafunctions</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">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span> <span class="keyword">const</span><span class="special">&amp;</span></code> for some <code class="computeroutput"><span class="identifier">U</span></code>.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_value</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">type</span><span class="special">;</span></code>
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.example" title="Example">Example</a>
</h4></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="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">copy_const_reference</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">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="comment">// classes to wrap</span>
<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">struct</span> <span class="identifier">Foo</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="special">:</span> <span class="special">{</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
<span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span>
<span class="special">};</span>
<span class="comment">// Wrapper code</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">my_module</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Bar</span><span class="special">&gt;(</span><span class="string">"Bar"</span><span class="special">);</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;())</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span>
<span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special">&lt;</span><span class="identifier">copy_const_reference</span><span class="special">&gt;())</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">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">make</span> <span class="identifier">a</span> <span class="identifier">copy</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">internal</span> <span class="identifier">Bar</span> <span class="identifier">object</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe" title="boost/python/copy_non_const_reference.hpp">boost/python/copy_non_const_reference.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference">Class
<code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference_m">Class
<code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code>
metafunctions</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference" title="Class copy_non_const_reference">Class
<code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code></a>
</h4></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code>
is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a>
which can be used to wrap C++ functions returning a reference-to-non-const
type such that the referenced value is copied into a new Python object.
</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">struct</span> <span class="identifier">copy_non_const_reference</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">struct</span> <span class="identifier">apply</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference_m"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference_m" title="Class copy_non_const_reference metafunctions">Class
<code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code>
metafunctions</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">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span> <span class="special">&amp;</span></code>
for some non-const <code class="computeroutput"><span class="identifier">U</span></code>.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_value</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">type</span></code>;
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.example" title="Example">Example</a>
</h4></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="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">copy_non_const_reference</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">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="comment">// classes to wrap</span>
<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">struct</span> <span class="identifier">Foo</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="special">:</span> <span class="special">{</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
<span class="identifier">Bar</span><span class="special">&amp;</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span>
<span class="special">};</span>
<span class="comment">// Wrapper code</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">my_module</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Bar</span><span class="special">&gt;(</span><span class="string">"Bar"</span><span class="special">);</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;())</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span>
<span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special">&lt;</span><span class="identifier">copy_non_const_reference</span><span class="special">&gt;())</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">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">make</span> <span class="identifier">a</span> <span class="identifier">copy</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">internal</span> <span class="identifier">Bar</span> <span class="identifier">object</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h" title="boost/python/manage_new_object.hpp">boost/python/manage_new_object.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object">Class
<code class="computeroutput"><span class="identifier">manage_new_object</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object_metafunc">Class
<code class="computeroutput"><span class="identifier">manage_new_object</span></code> metafunctions</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object" title="Class manage_new_object">Class
<code class="computeroutput"><span class="identifier">manage_new_object</span></code></a>
</h4></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">manage_new_object</span></code> is
a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a>
which can be used to wrap C++ functions which return a pointer to an
object allocated with a new-expression, and expect the caller to take
responsibility for deleting that object.
</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">struct</span> <span class="identifier">manage_new_object</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">struct</span> <span class="identifier">apply</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object_metafunc"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object_metafunc" title="Class manage_new_object metafunctions">Class
<code class="computeroutput"><span class="identifier">manage_new_object</span></code> metafunctions</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">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span><span class="special">*</span></code>
for some <code class="computeroutput"><span class="identifier">U</span></code>.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_indirect</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">type</span><span class="special">;</span></code>
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.example" title="Example">Example</a>
</h4></div></div></div>
<p>
In C++:
</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">manage_new_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">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">Foo</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="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="identifier">x</span><span class="special">){}</span>
<span class="keyword">int</span> <span class="identifier">get_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="keyword">int</span> <span class="identifier">x</span><span class="special">;</span>
<span class="special">};</span>
<span class="identifier">Foo</span><span class="special">*</span> <span class="identifier">make_foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">new</span> <span class="identifier">Foo</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> <span class="special">}</span>
<span class="comment">// Wrapper code</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">my_module</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"make_foo"</span><span class="special">,</span> <span class="identifier">make_foo</span><span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special">&lt;</span><span class="identifier">manage_new_object</span><span class="special">&gt;())</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;(</span><span class="string">"Foo"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_x"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_x</span><span class="special">)</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">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">make_foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span>
<span class="number">3</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_" title="boost/python/reference_existing_object.hpp">boost/python/reference_existing_object.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object">Class
<code class="computeroutput"><span class="identifier">reference_existing_object</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object_">Class
<code class="computeroutput"><span class="identifier">reference_existing_object</span></code>
metafunctions</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object" title="Class reference_existing_object">Class
<code class="computeroutput"><span class="identifier">reference_existing_object</span></code></a>
</h4></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">reference_existing_object</span></code>
is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a>
which can be used to wrap C++ functions which return a reference or pointer
to a C++ object. When the wrapped function is called, the value referenced
by its return value is not copied. A new Python object is created which
contains a pointer to the referent, and no attempt is made to ensure
that the lifetime of the referent is at least as long as that of the
corresponding Python object. Thus, it can be <span class="bold"><strong>highly
dangerous</strong></span> to use <code class="computeroutput"><span class="identifier">reference_existing_object</span></code>
without additional lifetime management from such models of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>
as <a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward" title="Class with_custodian_and_ward"><code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code></a>. This
class is used in the implementation of <a class="link" href="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"><code class="computeroutput"><span class="identifier">return_internal_reference</span></code></a>.
</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">struct</span> <span class="identifier">reference_existing_object</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">struct</span> <span class="identifier">apply</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object_"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object_" title="Class reference_existing_object metafunctions">Class
<code class="computeroutput"><span class="identifier">reference_existing_object</span></code>
metafunctions</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">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
<code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span><span class="special">&amp;</span></code>
or <code class="computeroutput"><span class="identifier">U</span><span class="special">*</span></code>
for some <code class="computeroutput"><span class="identifier">U</span></code>.
</p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
<code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_indirect</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">V</span><span class="special">&gt;</span> <span class="identifier">type</span><span class="special">;</span></code>, where V is a class whose static
execute function constructs an instance holder containing an unowned
<code class="computeroutput"><span class="identifier">U</span><span class="special">*</span></code>
pointing to the referent of the wrapped function's return value.
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.example" title="Example">Example</a>
</h4></div></div></div>
<p>
In C++:
</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">reference_existing_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">return_value_policy</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">utility</span><span class="special">&gt;</span>
<span class="comment">// classes to wrap</span>
<span class="keyword">struct</span> <span class="identifier">Singleton</span>
<span class="special">{</span>
<span class="identifier">Singleton</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">{}</span>
<span class="keyword">int</span> <span class="identifier">exchange</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">)</span> <span class="comment">// set x and return the old value</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">swap</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">return</span> <span class="identifier">n</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span>
<span class="special">};</span>
<span class="identifier">Singleton</span><span class="special">&amp;</span> <span class="identifier">get_it</span><span class="special">()</span>
<span class="special">{</span>
<span class="keyword">static</span> <span class="identifier">Singleton</span> <span class="identifier">just_one</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">just_one</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">// Wrapper code</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">singleton</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">def</span><span class="special">(</span><span class="string">"get_it"</span><span class="special">,</span> <span class="identifier">get_it</span><span class="special">,</span>
<span class="identifier">return_value_policy</span><span class="special">&lt;</span><span class="identifier">reference_existing_object</span><span class="special">&gt;());</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Singleton</span><span class="special">&gt;(</span><span class="string">"Singleton"</span><span class="special">)</span>
<span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"exchange"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Singleton</span><span class="special">::</span><span class="identifier">exchange</span><span class="special">)</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">singleton</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">s1</span> <span class="special">=</span> <span class="identifier">singleton</span><span class="special">.</span><span class="identifier">get_it</span><span class="special">()</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">s2</span> <span class="special">=</span> <span class="identifier">singleton</span><span class="special">.</span><span class="identifier">get_it</span><span class="special">()</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">id</span><span class="special">(</span><span class="identifier">s1</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">id</span><span class="special">(</span><span class="identifier">s2</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">s1</span> <span class="keyword">and</span> <span class="identifier">s2</span> <span class="identifier">are</span> <span class="keyword">not</span> <span class="identifier">the</span> <span class="identifier">same</span> <span class="identifier">object</span>
<span class="number">0</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">s1</span><span class="special">.</span><span class="identifier">exchange</span><span class="special">(</span><span class="number">42</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">but</span> <span class="identifier">they</span> <span class="identifier">reference</span> <span class="identifier">the</span> <span class="identifier">same</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">Singleton</span>
<span class="number">0</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">s2</span><span class="special">.</span><span class="identifier">exchange</span><span class="special">(</span><span class="number">99</span><span class="special">)</span>
<span class="number">42</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp" title="boost/python/return_by_value.hpp">boost/python/return_by_value.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value">Class
<code class="computeroutput"><span class="identifier">return_by_value</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value_metafuncti">Class
<code class="computeroutput"><span class="identifier">return_by_value</span></code> metafunctions</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value" title="Class return_by_value">Class
<code class="computeroutput"><span class="identifier">return_by_value</span></code></a>
</h4></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">return_by_value</span></code> is a
model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a>
which can be used to wrap C++ functions returning any reference or value
type such that the return value is copied into a new Python object.
</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">struct</span> <span class="identifier">return_by_value</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">struct</span> <span class="identifier">apply</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value_metafuncti"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value_metafuncti" title="Class return_by_value metafunctions">Class
<code class="computeroutput"><span class="identifier">return_by_value</span></code> metafunctions</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">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</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="keyword">typedef</span> <span class="identifier">to_python_value</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">type</span><span class="special">;</span></code>
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.example" title="Example">Example</a>
</h4></div></div></div>
<p>
In C++:
</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">return_by_value</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">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="comment">// classes to wrap</span>
<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="special">};</span>
<span class="identifier">Bar</span> <span class="identifier">global_bar</span><span class="special">;</span>
<span class="comment">// functions to wrap:</span>
<span class="identifier">Bar</span> <span class="identifier">b1</span><span class="special">();</span>
<span class="identifier">Bar</span><span class="special">&amp;</span> <span class="identifier">b2</span><span class="special">();</span>
<span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">b3</span><span class="special">();</span>
<span class="comment">// Wrapper code</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">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">def_void_function</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">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)())</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">f</span><span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special">&lt;</span><span class="identifier">return_by_value</span><span class="special">&gt;());</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Bar</span><span class="special">&gt;(</span><span class="string">"Bar"</span><span class="special">);</span>
<span class="identifier">def_void_function</span><span class="special">(</span><span class="string">"b1"</span><span class="special">,</span> <span class="identifier">b1</span><span class="special">);</span>
<span class="identifier">def_void_function</span><span class="special">(</span><span class="string">"b2"</span><span class="special">,</span> <span class="identifier">b2</span><span class="special">);</span>
<span class="identifier">def_void_function</span><span class="special">(</span><span class="string">"b3"</span><span class="special">,</span> <span class="identifier">b3</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">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">b1</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">each</span> <span class="identifier">of</span> <span class="identifier">these</span> <span class="identifier">calls</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">b2</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">creates</span> <span class="identifier">a</span> <span class="identifier">brand</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">b3</span><span class="special">()</span> <span class="special">#</span> <span class="keyword">new</span> <span class="identifier">Bar</span> <span class="identifier">object</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point" title="boost/python/return_opaque_pointer.hpp">boost/python/return_opaque_pointer.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaqe_pointer">Class
<code class="computeroutput"><span class="identifier">return_opaqe_pointer</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaque_pointer_meta">Class
<code class="computeroutput"><span class="identifier">return_opaque_pointer</span></code> metafunctions</a></span></dt>
<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaqe_pointer"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaqe_pointer" title="Class return_opaqe_pointer">Class
<code class="computeroutput"><span class="identifier">return_opaqe_pointer</span></code></a>
</h4></div></div></div>
<p>
return_opaque_pointer is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a>
which can be used to wrap C++ functions returning pointers to undefined
types such that the return value is copied into a new Python object.
</p>
<p>
In addition to specifying the <code class="computeroutput"><span class="identifier">return_opaque_pointer</span></code>
policy the <a class="link" href="../to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia" title="Macro BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(Pointee)"><code class="computeroutput"><span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span></code></a>
macro must be used to define specializations for the <a class="link" href="../utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.functions" title="Functions"><code class="computeroutput"><span class="identifier">type_id</span></code></a> function on the type
pointed to by returned pointer.
</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">struct</span> <span class="identifier">return_opaque_pointer</span>
<span class="special">{</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaque_pointer_meta"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaque_pointer_meta" title="Class return_opaque_pointer metafunctions">Class
<code class="computeroutput"><span class="identifier">return_opaque_pointer</span></code> metafunctions</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">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</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">detail</span><span class="special">::</span><span class="identifier">opaque_conversion_holder</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;</span>
<span class="identifier">type</span><span class="special">;</span></code>
</p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.example" title="Example">Example</a>
</h4></div></div></div>
<p>
In C++:
</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">return_opaque_pointer</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="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">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">typedef</span> <span class="keyword">struct</span> <span class="identifier">opaque_</span> <span class="special">*</span><span class="identifier">opaque</span><span class="special">;</span>
<span class="identifier">opaque</span> <span class="identifier">the_op</span> <span class="special">=</span> <span class="special">((</span><span class="identifier">opaque</span><span class="special">)</span> <span class="number">0x47110815</span><span class="special">);</span>
<span class="identifier">opaque</span> <span class="identifier">get</span> <span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">the_op</span><span class="special">;</span> <span class="special">}</span>
<span class="keyword">void</span> <span class="identifier">use</span> <span class="special">(</span><span class="identifier">opaque</span> <span class="identifier">op</span><span class="special">)</span> <span class="special">{</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">op</span> <span class="special">!=</span> <span class="identifier">the_op</span><span class="special">)</span>
<span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">(</span><span class="string">"failed"</span><span class="special">));</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="identifier">failuse</span> <span class="special">(</span><span class="identifier">opaque</span> <span class="identifier">op</span><span class="special">)</span> <span class="special">{</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">op</span> <span class="special">==</span> <span class="identifier">the_op</span><span class="special">)</span>
<span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">(</span><span class="string">"success"</span><span class="special">));</span>
<span class="special">}</span>
<span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span><span class="special">(</span><span class="identifier">opaque_</span><span class="special">)</span>
<span class="keyword">namespace</span> <span class="identifier">bpl</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">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">opaque_ext</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">bpl</span><span class="special">::</span><span class="identifier">def</span> <span class="special">(</span>
<span class="string">"get"</span><span class="special">,</span> <span class="special">&amp;::</span><span class="identifier">get</span><span class="special">,</span> <span class="identifier">bpl</span><span class="special">::</span><span class="identifier">return_value_policy</span><span class="special">&lt;</span><span class="identifier">bpl</span><span class="special">::</span><span class="identifier">return_opaque_pointer</span><span class="special">&gt;());</span>
<span class="identifier">bpl</span><span class="special">::</span><span class="identifier">def</span> <span class="special">(</span><span class="string">"use"</span><span class="special">,</span> <span class="special">&amp;::</span><span class="identifier">use</span><span class="special">);</span>
<span class="identifier">bpl</span><span class="special">::</span><span class="identifier">def</span> <span class="special">(</span><span class="string">"failuse"</span><span class="special">,</span> <span class="special">&amp;::</span><span class="identifier">failuse</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
Python code:
</p>
<pre class="programlisting"><span class="string">""</span><span class="string">"
&gt;&gt;&gt; from opaque_ext import *
&gt;&gt;&gt; #
&gt;&gt;&gt; # Check for correct conversion
&gt;&gt;&gt; use(get())
&gt;&gt;&gt; failuse(get())
Traceback (most recent call last):
...
RuntimeError: success
&gt;&gt;&gt; #
&gt;&gt;&gt; # Check that there is no conversion from integers ...
&gt;&gt;&gt; use(0)
Traceback (most recent call last):
...
TypeError: bad argument type for built-in operation
&gt;&gt;&gt; #
&gt;&gt;&gt; # ... and from strings to opaque objects
&gt;&gt;&gt; use("</span><span class="string">")
Traceback (most recent call last):
...
TypeError: bad argument type for built-in operation
"</span><span class="string">""</span>
<span class="identifier">def</span> <span class="identifier">run</span><span class="special">(</span><span class="identifier">args</span> <span class="special">=</span> <span class="identifier">None</span><span class="special">):</span>
<span class="identifier">import</span> <span class="identifier">sys</span>
<span class="identifier">import</span> <span class="identifier">doctest</span>
<span class="keyword">if</span> <span class="identifier">args</span> <span class="identifier">is</span> <span class="keyword">not</span> <span class="identifier">None</span><span class="special">:</span>
<span class="identifier">sys</span><span class="special">.</span><span class="identifier">argv</span> <span class="special">=</span> <span class="identifier">args</span>
<span class="keyword">return</span> <span class="identifier">doctest</span><span class="special">.</span><span class="identifier">testmod</span><span class="special">(</span><span class="identifier">sys</span><span class="special">.</span><span class="identifier">modules</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">__name__</span><span class="special">))</span>
<span class="keyword">if</span> <span class="identifier">__name__</span> <span class="special">==</span> <span class="char">'__main__'</span><span class="special">:</span>
<span class="identifier">print</span> <span class="string">"running..."</span>
<span class="identifier">import</span> <span class="identifier">sys</span>
<span class="identifier">sys</span><span class="special">.</span><span class="identifier">exit</span><span class="special">(</span><span class="identifier">run</span><span class="special">()[</span><span class="number">0</span><span class="special">])</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="models_of_resultconverter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.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="../to_from_python_type_conversion.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>