diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2013-06-25 22:59:01 +0000 |
|---|---|---|
| committer | <> | 2013-09-27 11:49:28 +0000 |
| commit | 8c4528713d907ee2cfd3bfcbbad272c749867f84 (patch) | |
| tree | c09e2ce80f47b90c85cc720f5139089ad9c8cfff /libs/python/doc/v2/has_back_reference.html | |
| download | boost-tarball-baserock/morph.tar.gz | |
Imported from /home/lorry/working-area/delta_boost-tarball/boost_1_54_0.tar.bz2.boost_1_54_0baserock/morph
Diffstat (limited to 'libs/python/doc/v2/has_back_reference.html')
| -rw-r--r-- | libs/python/doc/v2/has_back_reference.html | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/libs/python/doc/v2/has_back_reference.html b/libs/python/doc/v2/has_back_reference.html new file mode 100644 index 000000000..29b81506c --- /dev/null +++ b/libs/python/doc/v2/has_back_reference.html @@ -0,0 +1,225 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- 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 name="generator" content= + "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - <boost/python/has_back_reference.hpp></title> + + <style type="text/css"> + p.c3 {font-style: italic} + h2.c2 {text-align: center} + h1.c1 {text-align: center} + </style> + </head> + + <body> + <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../../index.htm"><img height="86" width="277" + alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">Header + <boost/python/has_back_reference.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#has_back_reference-spec">Class template + <code>has_back_reference</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#has_back_reference-spec-synopsis">Class template + <code>has_back_reference</code> synopsis</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + </dd> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/has_back_reference.hpp></code> defines the + predicate metafunction <code>has_back_reference<></code>, which can + be specialized by the user to indicate that a wrapped class instance + holds a <code>PyObject*</code> corresponding to a Python object.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="has_back_reference-spec"></a>Class template + <code>has_back_reference</code></h3> + + <p>A unary metafunction whose <code>value</code> is true iff its argument + is a <code>pointer_wrapper<></code>.</p> + + <h4><a name="has_back_reference-spec-synopsis"></a>Class template + <code>has_back_reference</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template<class WrappedClass> class has_back_reference + { + typedef mpl::false_ type; + }; +}} +</pre> + <p>A "<a href="../../../mpl/doc/refmanual/metafunction.html"> + metafunction</a>" that is inspected by Boost.Python to determine how + wrapped classes can be constructed.</p> + + <dl class="traits-semantics"> + <dt><code>type::value</code> is an integral constant convertible to bool + of unspecified type.</dt> + + <dt>Specializations may substitute a <code>true</code>-valued integral constant wrapper for + <code>type</code> iff for each invocation of + <code>class_<WrappedClass>::def(init<</code> + <i>type-sequence...</i><code>>())</code> and the implicitly wrapped + copy constructor (unless it is <a href="class.html#class_-spec"> + noncopyable</a>), there exists a corresponding constructor + <code>WrappedClass::WrappedClass(PyObject*, </code> + <i>type-sequence...</i><code>)</code>. If such a specialization exists, + the <code>WrappedClass</code> constructors will be called with a "back + reference" pointer to the corresponding Python object whenever they are + invoked from Python. The easiest way to provide this nested <code> +type +</code> + is to + derive the specialization from <code>mpl::true_</code>. + </dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/class.hpp> +#include <boost/python/module.hpp> +#include <boost/python/has_back_reference.hpp> +#include <boost/python/handle.hpp> +#include <boost/shared_ptr.hpp> + +using namespace boost::python; +using boost::shared_ptr; + +struct X +{ + X(PyObject* self) : m_self(self), m_x(0) {} + X(PyObject* self, int x) : m_self(self), m_x(x) {} + X(PyObject* self, X const& other) : m_self(self), m_x(other.m_x) {} + + handle<> self() { return handle<>(borrowed(m_self)); } + int get() { return m_x; } + void set(int x) { m_x = x; } + + PyObject* m_self; + int m_x; +}; + +// specialize has_back_reference for X +namespace boost { namespace python +{ + template <> + struct has_back_reference<X> + : mpl::true_ + {}; +}} + +struct Y +{ + Y() : m_x(0) {} + Y(int x) : m_x(x) {} + int get() { return m_x; } + void set(int x) { m_x = x; } + + int m_x; +}; + +shared_ptr<Y> +Y_self(shared_ptr<Y> self) { return self; } + +BOOST_PYTHON_MODULE(back_references) +{ + class_<X>("X") + .def(init<int>()) + .def("self", &X::self) + .def("get", &X::get) + .def("set", &X::set) + ; + + class_<Y, shared_ptr<Y> >("Y") + .def(init<int>()) + .def("get", &Y::get) + .def("set", &Y::set) + .def("self", Y_self) + ; +} +</pre> + The following Python session illustrates that <code>x.self()</code> + returns the same Python object on which it is invoked, while + <code>y.self()</code> must create a new Python object which refers to the + same Y instance. + + <h3>Python code</h3> +<pre> +>>> from back_references import * +>>> x = X(1) +>>> x2 = x.self() +>>> x2 is x +<b>1</b> +>>> (x.get(), x2.get()) +(1, 1) +>>> x.set(10) +>>> (x.get(), x2.get()) +(10, 10) +>>> +>>> +>>> y = Y(2) +>>> y2 = y.self() +>>> y2 is y +<b>0</b> +>>> (y.get(), y2.get()) +(2, 2) +>>> y.set(20) +>>> (y.get(), y2.get()) +(20, 20) +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 18 July, 2004 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p class="c3">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 +.</p> + </body> +</html> + |