1[section boost/python/return_internal_reference.hpp] 2[section Introduction] 3`return_internal_reference` instantiations are models of [link concepts.callpolicies `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. 4[endsect] 5[section Class template `return_internal_reference`] 6[table 7 [[Parameter][Requirements][Description][Default]] 8 [[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`). Note that if the target Python object type doesn't support weak references, a Python TypeError exception will be raised when the function being wrapped is called.][]] 9 [[Base][A model of [link concepts.callpolicies `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 [link concepts.callpolicies `CallPolicies`].][default_call_policies]] 10] 11`` 12namespace boost { namespace python 13{ 14 template <std::size_t owner_arg = 1, class Base = default_call_policies> 15 struct return_internal_reference : Base 16 { 17 static PyObject* postcall(PyObject*, PyObject* result); 18 typedef reference_existing_object result_converter; 19 }; 20}} 21`` 22[endsect] 23[section Class `return_internal_reference` static functions] 24``PyObject* postcall(PyObject* args, PyObject* result);`` 25[variablelist 26[[Requires][`PyTuple_Check(args) != 0`]] 27[[Returns][[link function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st `with_custodian_and_ward_postcall::postcall(args, result)`]]] 28] 29[endsect] 30[section Example] 31C++ module definition: 32`` 33#include <boost/python/module.hpp> 34#include <boost/python/class.hpp> 35#include <boost/python/return_internal_reference.hpp> 36 37class Bar 38{ 39 public: 40 Bar(int x) : x(x) {} 41 int get_x() const { return x; } 42 void set_x(int x) { this->x = x; } 43 private: 44 int x; 45}; 46 47class Foo 48{ 49 public: 50 Foo(int x) : b(x) {} 51 52 // Returns an internal reference 53 Bar const& get_bar() const { return b; } 54 55 private: 56 Bar b; 57}; 58 59using namespace boost::python; 60BOOST_PYTHON_MODULE(internal_refs) 61{ 62 class_<Bar>("Bar", init<int>()) 63 .def("get_x", &Bar::get_x) 64 .def("set_x", &Bar::set_x) 65 ; 66 67 class_<Foo>("Foo", init<int>()) 68 .def("get_bar", &Foo::get_bar 69 , return_internal_reference<>()) 70 ; 71} 72`` 73Python code: 74`` 75>>> from internal_refs import * 76>>> f = Foo(3) 77>>> b1 = f.get_bar() 78>>> b2 = f.get_bar() 79>>> b1.get_x() 803 81>>> b2.get_x() 823 83>>> b1.set_x(42) 84>>> b2.get_x() 8542 86`` 87[endsect] 88[endsect] 89