| <!-- 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> |
| |
| |