[pygccxml-commit] SF.net SVN: pygccxml:[1427] pyplusplus_dev/docs/documentation/functions/ call_policies/return_pointee_value.rest

[<rom...@us...>]

Revision: 1427
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1427&view=rev
Author:   roman_yakovenko
Date:     2008-10-06 15:01:03 +0000 (Mon, 06 Oct 2008)

Log Message:
-----------
update documentation

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/functions/call_policies/return_pointee_value.rest

Modified: pyplusplus_dev/docs/documentation/functions/call_policies/return_pointee_value.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/call_policies/return_pointee_value.rest	2008-10-05 21:22:28 UTC (rev 1426)
+++ pyplusplus_dev/docs/documentation/functions/call_policies/return_pointee_value.rest	2008-10-06 15:01:03 UTC (rev 1427)
@@ -8,16 +8,93 @@
 Definition
 ----------
 
-Class ``return_pointee_value`` is a model of `ResultConverterGenerator`_  which
-can be used to wrap C++ functions returning any pointer, such that the pointee of
-return value is copied into a new Python object.
+Class ``return_pointee_value`` is a model of `ResultConverterGenerator`_ which 
+can be used to wrap C++ functions, that return a pointer to a C++ object. The 
+policy implements the following logic:
 
--------
-Example
--------
+.. code-block:: C++
 
+  if( <<<return value is NULL pointer>>> ){
+      return None;
+  }    
+  else{
+      return boost::python::object( *<<<return value>>> );
+  }
+
+The return type of the function should be ``T*``.
+
+It passes the value of the pointee to `Python`_, thus the conversion for ``T`` 
+is used. This call policy could be used to return pointers to `Python`_, which 
+types are not known to `Boost.Python`_, but only a conversion for the pointees. 
+
+Therefore this policy should be used to return pointers to objects, whose types 
+were wrapped with other tools, such as SWIG\SIP. 
+
+Another usage of this call policy is to return to Python new object, which contains
+copy of ``(*return value)``.
+
+Please note: This policy does not take ownership of the wrapped pointer. If the 
+object pointed to is deleted in C++, the python-object will become invalid too, 
+if your custom conversion depends on the original object.
+
+--------
+Examples
+--------
+
+Unknown type
+------------
+
+This technique and example was contributed by Maximilian Matthe.
+
 .. code-block:: C++
 
+  struct int_wrapper{
+       int_wrapper(int v) 
+       : val(v) 
+       {}
+       
+       int val;
+  };
+  
+  //we will expose the following function
+  int_wrapper* return_int_wrapper(){
+       static int_wrapper w(42);
+       return &w;
+  }
+  
+  //the Boost.Python custom converter
+  struct convert_int_wrapper{
+      static PyObject* convert(int_wrapper const& w){
+          boost::python::object value(w.val);
+          return boost::python::incref( value.ptr() );
+      }
+  };
+  
+  
+  BOOST_PYTHON_MODULE(my_module){       
+       using namespace boost::python;
+       //register our custom converter
+       to_python_converter<int_wrapper, convert_int_wrapper, false>();
+       
+       def( "return_int_wrapper"
+            , &return_int_wrapper
+            , return_value_policy<return_pointee_value>() );
+  }
+
+Python code:
+
+.. code-block:: Python
+
+  import my_module
+  
+  assert 42 == my_module.return_int_wrapper()
+
+
+Return pointee value
+--------------------
+
+.. code-block:: C++
+
   float* get_value(){
       static float value = 0.5;
       return &value;
@@ -57,7 +134,6 @@
   assert None is my_module.get_null_value()
 
 
-
 .. _`ResultConverterGenerator` : http://boost.org/libs/python/doc/v2/ResultConverter.html#ResultConverterGenerator-concept
 .. _`CallPolicies` : http://www.boost.org/libs/python/doc/v2/CallPolicies.html#CallPolicies-concept
 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.