1[section boost/python/ptr.hpp] 2[section Introduction] 3<boost/python/ptr.hpp> defines the ptr() function template, which allows users to specify how to convert C++ pointer values to python in the context of implementing overridable virtual functions, invoking Python callable objects, or explicitly converting C++ objects to Python. Normally, when passing pointers to Python callbacks, the pointee is copied to ensure that the Python object never holds a dangling reference. To specify that the new Python object should merely contain a copy of a pointer p, the user can pass ptr(p) instead of passing p directly. This interface is meant to mirror the use of boost::ref(), which can be similarly used to prevent copying of referents. 4 5ptr(p) returns an instance of [link function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper `pointer_wrapper<>`], which can be detected using the [link function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe `is_pointer_wrapper<>`] metafunction; [link function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer `unwrap_pointer<>`] is a metafunction which extracts the original pointer type from a `pointer_wrapper<>`. These classes can be thought of as implementation details. 6[endsect] 7[section Functions] 8`` 9template <class T> 10pointer_wrapper<T> ptr(T x); 11`` 12[variablelist 13[[Requires][T is a pointer type.]] 14[[Returns][pointer_wrapper<T>(x)]] 15[[Throws][nothing.]] 16] 17[endsect] 18[section Class template `pointer_wrapper`] 19A "type envelope" which is returned by `ptr()`, used to indicate reference semantics for pointers passed to Python callbacks. 20`` 21namespace boost { namespace python 22{ 23 template<class Ptr> class pointer_wrapper 24 { 25 public: 26 typedef Ptr type; 27 28 explicit pointer_wrapper(Ptr x); 29 operator Ptr() const; 30 Ptr get() const; 31 }; 32}} 33`` 34[endsect] 35[section Class template `pointer_wrapper` types] 36`` 37typedef Ptr type; 38`` 39The type of the pointer being wrapped. 40[endsect] 41[section Class template `pointer_wrapper` constructors and destructor] 42`` 43explicit pointer_wrapper(Ptr x); 44`` 45[variablelist 46[[Requires][`Ptr` is a pointer type]] 47[[Effects][Stores `x` in a the `pointer_wrapper<>`. ]] 48[[Throws][nothing.]] 49] 50[endsect] 51[section Class template `pointer_wrapper` observer functions] 52`` 53operator Ptr() const; 54Ptr get() const; 55`` 56[variablelist 57[[Returns][a copy of the stored pointer. ]] 58[[Rationale][pointer_wrapper is intended to be a stand-in for the actual pointer type, but sometimes it's better to have an explicit way to retrieve the pointer. ]] 59] 60[endsect] 61[section Metafunctions] 62[section Class template `is_pointer_wrapper`] 63A unary metafunction whose value is true iff its argument is a pointer_wrapper<>. 64`` 65namespace boost { namespace python 66{ 67 template<class T> class is_pointer_wrapper 68 { 69 static unspecified value = ...; 70 }; 71}} 72`` 73[variablelist 74[[Returns][`true` iff `T` is a specialization of `pointer_wrapper<>`. 75value is an integral constant convertible to bool of unspecified type ]] 76] 77[endsect] 78[section Class template `unwrap_pointer`] 79A unary metafunction which extracts the wrapped pointer type from a specialization of pointer_wrapper<>. 80`` 81namespace boost { namespace python 82{ 83 template<class T> class unwrap_pointer 84 { 85 typedef unspecified type; 86 }; 87}} 88`` 89[variablelist 90[[Returns][`T::type` if `T` is a specialization of `pointer_wrapper<>`, `T` otherwise ]] 91] 92[endsect] 93[endsect] 94[section Example] 95This example illustrates the use of ptr() to prevent an object from being copied: 96`` 97#include <boost/python/call.hpp> 98#include <boost/python/ptr.hpp> 99 100class expensive_to_copy 101{ 102 ... 103}; 104 105void pass_as_arg(expensive_to_copy* x, PyObject* f) 106{ 107 // call the Python function f, passing a Python object built around 108 // which refers to *x by-pointer. 109 // 110 // *** Note: ensuring that *x outlives the argument to f() is *** 111 // *** up to the user! Failure to do so could result in a crash! *** 112 113 boost::python::call<void>(f, ptr(x)); 114} 115... 116`` 117[endsect] 118[endsect] 119