diff options
Diffstat (limited to 'libs/python/doc/v2/register_ptr_to_python.html')
| -rw-r--r-- | libs/python/doc/v2/register_ptr_to_python.html | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/libs/python/doc/v2/register_ptr_to_python.html b/libs/python/doc/v2/register_ptr_to_python.html new file mode 100644 index 000000000..5f660e18f --- /dev/null +++ b/libs/python/doc/v2/register_ptr_to_python.html @@ -0,0 +1,162 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../boost.css"> +<title>Boost.Python - <register_ptr_to_python.hpp></title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../../index.htm"><img height="86" width="277" alt= + "C++ Boost" src="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Header <register_ptr_to_python.hpp></h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#functions">Functions</a></dt> + <dl class="page-index"> + <dt><a href="#register_ptr_to_python-spec">register_ptr_to_python</a></dt> + </dl> + + <dt><a href="#examples">Example(s)</a></dt> + +</dl> +<hr> +<h2><a name="introduction"></a>Introduction</h2> +<p> + <code><boost/python/register_ptr_to_python.hpp></code> + supplies <code>register_ptr_to_python</code>, a function template + which registers a conversion for smart pointers to Python. The + resulting Python object holds a copy of the converted smart pointer, + but behaves as though it were a wrapped copy of the pointee. If + the pointee type has virtual functions and the class representing + its dynamic (most-derived) type has been wrapped, the Python object + will be an instance of the wrapper for the most-derived type. More than + one smart pointer type for a pointee's class can be registered. +</p> +<p> + Note that in order to convert a Python <code>X</code> object to a + <code>smart_ptr<X>&</code> (non-const reference), the embedded C++ + object must be held by <code>smart_ptr<X></code>, and that when wrapped + objects are created by calling the constructor from Python, how they are held + is determined by the <code>HeldType</code> parameter to + <code>class_<...></code> instances. +</p> + +<h2><a name="functions"></a>Functions</h2> +<pre> +<a name="register_ptr_to_python-spec">template <class P> +void register_ptr_to_python() +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> <code>P</code> is <a href="Dereferenceable.html#Dereferenceable-concept">Dereferenceable</a>. + </dt> + <dt><b>Effects:</b> Allows conversions to-python of <code>P</code> + instances. + </dt> +</dl> + +<h2><a name="examples"></a>Example(s)</h2> + +<h3>C++ Wrapper Code</h3> + +Here is an example of a module that contains a class <code>A</code> with +virtual functions and some functions that work with +<code>boost::shared_ptr<A></code>. + +<pre> +struct A +{ + virtual int f() { return 0; } +}; + +shared_ptr<A> New() { return shared_ptr<A>( new A() ); } + +int Ok( const shared_ptr<A>& a ) { return a->f(); } + +int Fail( shared_ptr<A>& a ) { return a->f(); } + +struct A_Wrapper: A +{ + A_Wrapper(PyObject* self_): self(self_) {} + int f() { return call_method<int>(self, "f"); } + int default_f() { return A::f(); } + PyObject* self; +}; + +BOOST_PYTHON_MODULE(register_ptr) +{ + class_<A, A_Wrapper>("A") + .def("f", &A::f, &A_Wrapper::default_f) + ; + + def("New", &New); + def("Ok", &Call); + def("Fail", &Fail); + + register_ptr_to_python< shared_ptr<A> >(); +} +</pre> + +<h3>Python Code</h3> + +<pre> +>>> from register_ptr import * +>>> a = A() +>>> Ok(a) # ok, passed as shared_ptr<A> +0 +>>> Fail(a) # passed as shared_ptr<A>&, and was created in Python! +Traceback (most recent call last): + File "<stdin>", line 1, in ? +TypeError: bad argument type for built-in operation +>>> +>>> na = New() # now "na" is actually a shared_ptr<A> +>>> Ok(a) +0 +>>> Fail(a) +0 +>>> +</pre> + +If <code>shared_ptr<A></code> is registered as follows: + +<pre> + class_<A, A_Wrapper, shared_ptr<A> >("A") + .def("f", &A::f, &A_Wrapper::default_f) + ; +</pre> + +There will be an error when trying to convert <code>shared_ptr<A></code> to +<code>shared_ptr<A_Wrapper></code>: + +<pre> +>>> a = New() +Traceback (most recent call last): +File "<stdin>", line 1, in ? +TypeError: No to_python (by-value) converter found for C++ type: class boost::shared_ptr<struct A> +>>> +</pre> + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 24 Jun, 2003 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> + + |