boost_1_45_0/libs/python/doc/v2/has_back_reference.html - nest-learning-thermostat/5.0/boost - Git at Google

 <!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 - &lt;boost/python/has_back_reference.hpp&gt;</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
           &lt;boost/python/has_back_reference.hpp&gt;</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>&lt;boost/python/has_back_reference.hpp&gt;</code> defines the
     predicate metafunction <code>has_back_reference&lt;&gt;</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&lt;&gt;</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&lt;class WrappedClass&gt; 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_&lt;WrappedClass&gt;::def(init&lt;</code>
       <i>type-sequence...</i><code>&gt;())</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*,&nbsp;</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 &lt;boost/python/class.hpp&gt;
 #include &lt;boost/python/module.hpp&gt;
 #include &lt;boost/python/has_back_reference.hpp&gt;
 #include &lt;boost/python/handle.hpp&gt;
 #include &lt;boost/shared_ptr.hpp&gt;

 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&lt;&gt; self() { return handle&lt;&gt;(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 &lt;&gt;
   struct has_back_reference&lt;X&gt;
     : 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&lt;Y&gt;
 Y_self(shared_ptr&lt;Y&gt; self) { return self; }

 BOOST_PYTHON_MODULE(back_references)
 {
     class_&lt;X&gt;("X")
        .def(init&lt;int&gt;())
        .def("self", &amp;X::self)
        .def("get", &amp;X::get)
        .def("set", &amp;X::set)
        ;

     class_&lt;Y, shared_ptr&lt;Y&gt; &gt;("Y")
        .def(init&lt;int&gt;())
        .def("get", &amp;Y::get)
        .def("set", &amp;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>
 &gt;&gt;&gt; from back_references import *
 &gt;&gt;&gt; x = X(1)
 &gt;&gt;&gt; x2 = x.self()
 &gt;&gt;&gt; x2 is x
 <b>1</b>
 &gt;&gt;&gt; (x.get(), x2.get())
 (1, 1)
 &gt;&gt;&gt; x.set(10)
 &gt;&gt;&gt; (x.get(), x2.get())
 (10, 10)
 &gt;&gt;&gt;
 &gt;&gt;&gt;
 &gt;&gt;&gt; y = Y(2)
 &gt;&gt;&gt; y2 = y.self()
 &gt;&gt;&gt; y2 is y
 <b>0</b>
 &gt;&gt;&gt; (y.get(), y2.get())
 (2, 2)
 &gt;&gt;&gt; y.set(20)
 &gt;&gt;&gt; (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">&copy; Copyright <a href=
     "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002
 .</p>
   </body>
 </html>
	<!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>