diff --git a/doc/v2/class.html b/doc/v2/class.html index 85e24993..fc64eabd 100644 --- a/doc/v2/class.html +++ b/doc/v2/class.html @@ -191,7 +191,7 @@ template <class F> class_& def(char const* name, F f) template <class Fn, class CallPolicy> -class_& def(char const* name, Fn fn, CallPolicy policy) +class_& def(char const* name, Fn f, CallPolicy policy)
@@ -199,8 +199,11 @@ class_& def(char const* name, Fn fn, CallPolicy policy) pointer-to-member-function. name is a ntbs which conforms to Python's identifier - naming rules. If supplied, policy conforms to the CallPolicy concept requirements. + naming rules. In the first form, the return type of + f is not a reference and is not a pointer other + than char const* or PyObject*. In the + second form policy is a model of CallPolicies.
Effects: Adds the result of make_function(f) to diff --git a/doc/v2/header.html b/doc/v2/header.html index 7b36a65c..7b65547d 100644 --- a/doc/v2/header.html +++ b/doc/v2/header.html @@ -49,27 +49,22 @@
-
Class {{class name}} +
Class {{name}}
-
Class {{class - name}} synopsis +
Class {{name}} synopsis -
Class {{class name}} +
Class {{name}} constructors and destructor -
Class {{class - name}} comparison functions +
Class {{name}} comparison functions -
Class {{class - name}} modifier functions +
Class {{name}} modifier functions -
Class {{class - name}} observer functions +
Class {{name}} observer functions -
Class {{class - name}} static functions +
Class {{name}} static functions
@@ -113,7 +108,7 @@

{{class overview text}} -

Class {{name}} synopsis

+

Class {{name}} synopsis

 namespace boost
 {
@@ -123,7 +118,7 @@ namespace boost
 };
-

Class {{name}} constructors and +

Class {{name}} constructors and destructor

 {{constructor}}
@@ -164,7 +159,7 @@ namespace boost
       
Rationale: {{text}}
-

Class {{name}} comparison +

Class {{name}} comparison functions

 {{function}}
@@ -186,7 +181,7 @@ namespace boost
       
Rationale: {{text}}
     
 
-    
Class {{name}} modifier
+    
Class {{name}} modifier
     functions

 
 {{function}}
@@ -208,7 +203,7 @@ namespace boost
       
Rationale: {{text}}
     
 
-    
Class {{name}} observer
+    
Class {{name}} observer
     functions

 
 {{function}}
@@ -230,7 +225,7 @@ namespace boost
       
Rationale: {{text}}
     
 
-    
Class {{name}} static functions

+    
Class {{name}} static functions

 
 {{function}}
 

diff --git a/doc/v2/module.html b/doc/v2/module.html
index f39ff4e8..0e3516ed 100644
--- a/doc/v2/module.html
+++ b/doc/v2/module.html
@@ -188,19 +188,23 @@ module& add(class_<T,Bases,HolderGenerator> const& c);
     
 
 template <class Fn>
-module& def(char const* name, Fn fn);
+module& def(char const* name, Fn f);
 
 template <class Fn, class ResultHandler>
-module& def(char const* name, Fn fn, ResultHandler handler);
+module& def(char const* name, Fn f, ResultHandler handler);
 

 
     

+
       
Requires: f is a non-null pointer-to-function or
       pointer-to-member-function. name is a ntbs which conforms to
       Python's identifier
-      naming rules. If supplied, policy conforms to the CallPolicy concept requirements.
+      naming rules. In the first form, the return type of
+      f is not a reference and is not a pointer other
+      than char const* or PyObject*. In the
+      second form policy is a model of CallPolicy.
 
       
Effects: Adds the result of make_function(f) to
diff --git a/doc/v2/reference.html b/doc/v2/reference.html
index 5e2e4463..5f82fe4d 100644
--- a/doc/v2/reference.html
+++ b/doc/v2/reference.html
@@ -353,19 +353,19 @@
             

 
           
reference_from_python.hpp
+          "lvalue_from_python.html">reference_from_python.hpp
 
           

             

-              
Classes
+              
Classes
 
               

                 

                   
reference_from_python
+                  "lvalue_from_python.html#reference_from_python-spec">reference_from_python
 
                   
get_member
+                  "lvalue_from_python.html#get_member-spec">get_member
                 

             

         
diff --git a/doc/v2/return_internal_reference.html b/doc/v2/return_internal_reference.html
new file mode 100644
index 00000000..c1b62a56
--- /dev/null
+++ b/doc/v2/return_internal_reference.html
@@ -0,0 +1,205 @@
+
+    
+    
+    
+
+    Boost.Python - <boost/python/return_internal_reference.hpp>
+
+    
+      
+        

+          
+

+
+        		
+          
Boost.Python

+
+          
Header <boost/python/return_internal_reference.hpp>

+    

+    

+
+    
Contents

+
+    

+      
Introduction
+
+
+      
Classes
+
+      

+        

+          
Class Template return_internal_reference
+
+          

+            

+
+              
Class Template
+              return_internal_reference synopsis
+
+              
Class
+              return_internal_reference static functions
+            

+        

+
+
+      
Example
+    

+    

+
+    
Introduction

+
+    return_internal_reference instantiations are models of CallPolicies which allow pointers and
+    references to objects held internally by a free or member function
+    argument or from the target of a member function to be returned
+    safely without making a copy of the referent. The default for its
+    first template argument handles the common case where the
+    containing object is the target (*this) of a wrapped member function.
+
+    
Classes

+
+    
Class template return_internal_reference

+
+
+    
+      
+      
+        
+        
+        

+        return_internal_reference template parameters
+      
Parameter
+        
+        Requirements
+
+        Description
+
+        Default
+
+      
owner_arg 
+
+        A positive compile-time constant of type
+        std::size_t.
+
+        The index of the parameter which contains the object to
+        which the reference or pointer is being returned. If used to
+        wrap a member function, parameter 1 is the target object
+        (*this).
+
+        1
+
+      
Base 
+
+        A model of CallPolicies
+
+        Used for policy composition. Any
+        result_converter it supplies will be overridden by
+        return_internal_reference, but its
+        precall and postcall policies are
+        composed as described here CallPolicies.
+
+        default_call_policies
+
+    

+
+    
Class template return_internal_reference synopsis

+
+namespace boost { namespace python {
+   template <std::size_t owner_arg = 1, class Base = default_call_policies>
+   struct return_internal_reference : Base
+   {
+      static PyObject* postcall(PyObject*, PyObject* result);
+      typedef reference_existing_object result_converter;
+   };
+}}
+

+
+    
Class
+    default_call_policies static functions

+
+
+PyObject* postcall(PyObject* args, PyObject* result);
+

+
+    

+      
Requires: PyTuple_Check(args) != 0
+
+      
Returns: make_custodian_and_ward_postcall::postcall(args, result)
+    

+
+
+    
Example

+
+
C++ module definition

+
+
+#include <boost/python/module.hpp>
+#include <boost/python/class.hpp>
+#include <boost/python/return_internal_reference.hpp>
+
+class Bar
+{
+   Bar(int x) : x(x) {}
+   int get_x() const { return x; }
+   void set_x(int x) { this->x = x; }
+ private:
+   int x;
+}
+
+class Foo
+{
+ public:
+   Foo(int x) : b(x) {}
+
+   // Returns an internal reference
+   Bar const& get_bar() const { return b; }
+
+ private:
+   Bar b;
+};
+
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(internal_refs)
+{
+   module m("internal_refs")
+      .add(
+         class_<Bar>()
+            .def("get_x", &Bar::get_x)
+            .def("set_x", &Bar::set_x)
+         )
+      .add(
+         class_<Foo>()
+            .def_init(args<int>())
+            .def("get_bar", &Foo::get_bar
+                , return_internal_reference<>())
+         )
+      ;
+}
+

+
+
Python code

+
+
+>>> from internal_refs import *
+>>> f = Foo(3)
+>>> b1 = f.get_bar()
+>>> b2 = f.get_bar()
+>>> b1.get_x()
+3
+>>> b2.get_x()
+3
+>>> b1.set_x(42)
+>>> b2.get_x()
+42
+

+
+    
Revised 
+    
+    15 February, 2002
+    
+
+    
© Copyright Dave
+    Abrahams 2002. All Rights Reserved.
+