###

# Boost.Python

## Header <boost/python/to_python_indirect.hpp>

## Contents

Introduction
Classes
  Class Template `to_python_indirect`
    Class Template `to_python_indirect` synopsis
    Class Template `to_python_indirect` observer functions
    Class Template `to_python_indirect` static functions
Example

## Introduction

`<boost/python/to_python_indirect.hpp>` supplies a way to construct new Python objects that hold wrapped C++ class instances via a pointer or smart pointer.

## Classes

### Class template `to_python_indirect`

Class template `to_python_indirect` converts objects of its first argument type to python as extension class instances, using the ownership policy provided by its 2nd argument.

`to_python_indirect` Requirements
In the table below, `x` denotes an object of type `T`, `h` denotes an object of type `boost::python::objects::instance_holder*`, and `p` denotes an object of type `U*`.
Parameter | Requirements | Description
--- | --- | ---
`T` | Either `U` cv`&` (where cv is any optional cv-qualification) or a Dereferenceable type such that `*x` is convertible to `U const&`, where `U` is a class type. | A type deferencing a C++ class exposed to Python using class template `class_`.
`MakeHolder` | h = MakeHolder::execute(p); | A class whose static `execute()` creates an `instance_holder`.

Instantiations of `to_python_indirect` are models of ResultConverter.

#### Class template `to_python_indirect` synopsis

    namespace boost { namespace python
    {
      template <class T, class MakeHolder>
      struct to_python_indirect
      {
         static bool convertible();
         PyObject* operator()(T ptr_or_reference) const;
       private:
         static PyTypeObject* type();
      };
    }}

#### Class template `to_python_indirect` observers

    PyObject* operator()(T x) const;

Requires: `x` refers to an object (if it is a pointer type, it is non-null). `convertible() == true`.
Effects: Creates an appropriately-typed Boost.Python extension class instance, uses `MakeHolder` to create an `instance_holder` from `x`, installs the `instance_holder` in the new extension class instance, and returns a pointer to it.

#### Class template `to_python_indirect` statics

    bool convertible();

Effects: Returns `true` iff any module has registered a Python type corresponding to `U`.

## Example

This example replicates the functionality of reference_existing_object, but without some of the compile-time error checking.

    struct make_reference_holder
    {
       typedef boost::python::objects::instance_holder* result_type;
       template <class T>
       static result_type execute(T* p)
       {
          return new boost::python::objects::pointer_holder<T*, T>(p);
       }
    };

    struct reference_existing_object
    {
       // metafunction returning the ResultConverter
       template <class T>
       struct apply
       {
          typedef boost::python::to_python_indirect<T,make_reference_holder> type;
       };
    };

Revised 13 November, 2002

© Copyright Dave Abrahams 2002.