|  | 
<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.
          ptr(p) returns an instance of pointer_wrapper<>,
          which can be detected using the is_pointer_wrapper<>
          metafunction; unwrap_pointer<>
          is a metafunction which extracts the original pointer type from a pointer_wrapper<>.
          These classes can be thought of as implementation details.
        
template <class T> pointer_wrapper<T> ptr(T x);
T is a pointer type.
pointer_wrapper<T>(x)
nothing.
          A "type envelope" which is returned by ptr(), used to indicate reference semantics
          for pointers passed to Python callbacks.
        
namespace boost { namespace python { template<class Ptr> class pointer_wrapper { public: typedef Ptr type; explicit pointer_wrapper(Ptr x); operator Ptr() const; Ptr get() const; }; }}
explicit pointer_wrapper(Ptr x);
                Ptr is a pointer
                type
              
                Stores x in a the
                pointer_wrapper<>.
              
nothing.
operator Ptr() const; Ptr get() const;
a copy of the stored pointer.
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.
A unary metafunction whose value is true iff its argument is a pointer_wrapper<>.
namespace boost { namespace python { template<class T> class is_pointer_wrapper { static unspecified value = ...; }; }}
                  true iff T is a specialization of pointer_wrapper<>.
                  value is an integral constant convertible to bool of unspecified
                  type
                
A unary metafunction which extracts the wrapped pointer type from a specialization of pointer_wrapper<>.
namespace boost { namespace python { template<class T> class unwrap_pointer { typedef unspecified type; }; }}
                  T::type if T
                  is a specialization of pointer_wrapper<>, T
                  otherwise
                
This example illustrates the use of ptr() to prevent an object from being copied:
#include <boost/python/call.hpp> #include <boost/python/ptr.hpp> class expensive_to_copy { ... }; void pass_as_arg(expensive_to_copy* x, PyObject* f) { // call the Python function f, passing a Python object built around // which refers to *x by-pointer. // // *** Note: ensuring that *x outlives the argument to f() is *** // *** up to the user! Failure to do so could result in a crash! *** boost::python::call<void>(f, ptr(x)); } ...