Boost.Python - <boost/python/ptr.hpp>

###  | # Boost.Python ## Header <boost/python/ptr.hpp>

## Contents

Introduction
Functions
  ptr
Classes
  Class template `pointer_wrapper`
    Class template `pointer_wrapper` synopsis
    Class `pointer_wrapper` types
    Class `pointer_wrapper` constructors and destructor
    Class `pointer_wrapper` observer functions
Metafunctions
  Class template `is_pointer_wrapper`
    Class template `is_pointer_wrapper` synopsis
  Class template `unwrap_pointer`
    Class template `unwrap_pointer` synopsis
Example(s)

## Introduction

`<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.

## Functions

    template <class T>
    pointer_wrapper<T> ptr(T x);

Requires: `T` is a pointer type.
Returns: `pointer_wrapper<T>(x)`
Throws: nothing.

## Classes

### Class template `pointer_wrapper`

A "type envelope" which is returned by ptr(), used to indicate reference semantics for pointers passed to Python callbacks.

#### Class `pointer_wrapper` synopsis

    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;
        };
    }}

#### Class template `pointer_wrapper` types

    typedef Ptr type;

The type of the pointer being wrapped.

#### Class template `pointer_wrapper` constructors and destructor

    explicit pointer_wrapper(Ptr x);

Requires: `Ptr` is a pointer type.
Effects: Stores `x` in a the `pointer_wrapper<>`.
Throws: nothing.

#### Class template `pointer_wrapper` observer functions

    operator Ptr() const;
    Ptr get() const;

Returns: a copy of the stored pointer.
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.

## Metafunctions

### Class template `is_pointer_wrapper`

A unary metafunction whose `value` is true iff its argument is a `pointer_wrapper<>`.

#### Class template `is_pointer_wrapper` synopsis

    namespace boost { namespace python
    {
        template<class T> class is_pointer_wrapper
        {
            static unspecified value = ...;
        };
    }}

Returns: `true` iff `T` is a specialization of `pointer_wrapper<>`.
`value` is an integral constant convertible to bool of unspecified type

### Class template `unwrap_pointer`

A unary metafunction which extracts the wrapped pointer type from a specialization of `pointer_wrapper<>`.

#### Class template `unwrap_pointer` synopsis

    namespace boost { namespace python
    {
        template<class T> class unwrap_pointer
        {
            typedef unspecified type;
        };
    }}

Returns: `T::type` if `T` is a specialization of `pointer_wrapper<>`, `T` otherwise

## Example(s)

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));
    }
    ...

Revised 13 November, 2002

© Copyright Dave Abrahams 2002. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)