## Models of ResultConverterGenerator

### boost/python/copy_const_reference.hpp

#### Class `copy_const_reference`

`copy_const_reference` is a model of ResultConverterGenerator which can be used to wrap C++ functions returning a reference-to-const type such that the referenced value is copied into a new Python object.

    namespace boost { namespace python
    {
        struct copy_const_reference
        {
            template <class T> struct apply;
        };
    }}

#### Class `copy_const_reference` metafunctions

    template <class T> struct apply

Requires

  `T` is `U const&` for some `U`.

Returns

  `typedef to_python_value<T> type;`

#### Example

C++ module definition:

    #include <boost/python/module.hpp>
    #include <boost/python/class.hpp>
    #include <boost/python/copy_const_reference.hpp>
    #include <boost/python/return_value_policy.hpp>

    // classes to wrap
    struct Bar { int x; }

    struct Foo {
       Foo(int x) : { b.x = x; }
       Bar const& get_bar() const { return b; }
     private:
       Bar b;
    };

    // Wrapper code
    using namespace boost::python;
    BOOST_PYTHON_MODULE(my_module)
    {
        class_<Bar>("Bar");

         class_<Foo>("Foo", init<int>())
            .def("get_bar", &Foo::get_bar
                , return_value_policy<copy_const_reference>())
           ;
    }

Python code:

    >>> from my_module import *
    >>> f = Foo(3)         # create a Foo object
    >>> b = f.get_bar()    # make a copy of the internal Bar object

### boost/python/copy_non_const_reference.hpp

#### Class `copy_non_const_reference`

`copy_non_const_reference` is a model of ResultConverterGenerator which can be used to wrap C++ functions returning a reference-to-non-const type such that the referenced value is copied into a new Python object.

    namespace boost { namespace python
    {
        struct copy_non_const_reference
        {
            template <class T> struct apply;
        };
    }}

#### Class `copy_non_const_reference` metafunctions

    template <class T> struct apply

Requires

  `T` is `U &` for some non-const `U`.

Returns

  `typedef to_python_value<T> type`;

#### Example

C++ module definition:

    #include <boost/python/module.hpp>
    #include <boost/python/class.hpp>
    #include <boost/python/copy_non_const_reference.hpp>
    #include <boost/python/return_value_policy.hpp>

    // classes to wrap
    struct Bar { int x; }

    struct Foo {
       Foo(int x) : { b.x = x; }
       Bar& get_bar() { return b; }
     private:
       Bar b;
    };

    // Wrapper code
    using namespace boost::python;
    BOOST_PYTHON_MODULE(my_module)
    {
        class_<Bar>("Bar");

         class_<Foo>("Foo", init<int>())
            .def("get_bar", &Foo::get_bar
                , return_value_policy<copy_non_const_reference>())
           ;
    }

Python code:

    >>> from my_module import *
    >>> f = Foo(3)         # create a Foo object
    >>> b = f.get_bar()    # make a copy of the internal Bar object

### boost/python/manage_new_object.hpp

#### Class `manage_new_object`

`manage_new_object` is a model of ResultConverterGenerator which can be used to wrap C++ functions which return a pointer to an object allocated with a new-expression, and expect the caller to take responsibility for deleting that object.

    namespace boost { namespace python
    {
        struct manage_new_object
        {
            template <class T> struct apply;
        };
    }}

#### Class `manage_new_object` metafunctions

    template <class T> struct apply

Requires

  `T` is `U*` for some `U`.

Returns

  `typedef to_python_indirect<T> type;`

#### Example

In C++:

    #include <boost/python/module.hpp>
    #include <boost/python/class.hpp>
    #include <boost/python/manage_new_object.hpp>
    #include <boost/python/return_value_policy.hpp>

    struct Foo {
       Foo(int x) : x(x){}
       int get_x() { return x; }
       int x;
    };

    Foo* make_foo(int x) { return new Foo(x); }

    // Wrapper code
    using namespace boost::python;
    BOOST_PYTHON_MODULE(my_module)
    {
        def("make_foo", make_foo, return_value_policy<manage_new_object>())
        class_<Foo>("Foo")
            .def("get_x", &Foo::get_x)
            ;
    }

Python code:

    >>> from my_module import *
    >>> f = make_foo(3)     # create a Foo object
    >>> f.get_x()
    3

### boost/python/reference_existing_object.hpp

#### Class `reference_existing_object`

`reference_existing_object` is a model of ResultConverterGenerator which can be used to wrap C++ functions which return a reference or pointer to a C++ object. When the wrapped function is called, the value referenced by its return value is not copied. A new Python object is created which contains a pointer to the referent, and no attempt is made to ensure that the lifetime of the referent is at least as long as that of the corresponding Python object. Thus, it can be highly dangerous to use `reference_existing_object` without additional lifetime management from such models of CallPolicies as `with_custodian_and_ward`. This class is used in the implementation of `return_internal_reference`.

    namespace boost { namespace python
    {
        struct reference_existing_object
        {
            template <class T> struct apply;
        };
    }}

#### Class `reference_existing_object` metafunctions

    template <class T> struct apply

Requires

  `T` is `U&` or `U*` for some `U`.

Returns

  `typedef to_python_indirect<T, V> type;`, where V is a class whose static execute function constructs an instance holder containing an unowned `U*` pointing to the referent of the wrapped function's return value.

#### Example

In C++:

    #include <boost/python/module.hpp>
    #include <boost/python/class.hpp>
    #include <boost/python/reference_existing_object.hpp>
    #include <boost/python/return_value_policy.hpp>
    #include <utility>

    // classes to wrap
    struct Singleton
    {
       Singleton() : x(0) {}

       int exchange(int n)  // set x and return the old value
       {
            std::swap(n, x);
            return n;
       }

       int x;
    };

    Singleton& get_it()
    {
       static Singleton just_one;
       return just_one;
    }

    // Wrapper code
    using namespace boost::python;
    BOOST_PYTHON_MODULE(singleton)
    {
        def("get_it", get_it,
            return_value_policy<reference_existing_object>());

        class_<Singleton>("Singleton")
           .def("exchange", &Singleton::exchange)
           ;
    }

Python code:

    >>> import singleton
    >>> s1 = singleton.get_it()
    >>> s2 = singleton.get_it()
    >>> id(s1) == id(s2)  # s1 and s2 are not the same object
    0
    >>> s1.exchange(42)   # but they reference the same C++ Singleton
    0
    >>> s2.exchange(99)
    42

### boost/python/return_by_value.hpp

#### Class `return_by_value`

`return_by_value` is a model of ResultConverterGenerator which can be used to wrap C++ functions returning any reference or value type such that the return value is copied into a new Python object.

    namespace boost { namespace python
    {
        struct return_by_value
        {
            template <class T> struct apply;
        };
    }}

#### Class `return_by_value` metafunctions

    template <class T> struct apply

Returns

  `typedef to_python_value<T> type;`

#### Example

In C++:

    #include <boost/python/module.hpp>
    #include <boost/python/class.hpp>
    #include <boost/python/return_by_value.hpp>
    #include <boost/python/return_value_policy.hpp>

    // classes to wrap
    struct Bar { };

    Bar global_bar;

    // functions to wrap:
    Bar b1();
    Bar& b2();
    Bar const& b3();

    // Wrapper code
    using namespace boost::python;
    template <class R>
    void def_void_function(char const* name, R (*f)())
    {
       def(name, f, return_value_policy<return_by_value>());
    }

    BOOST_PYTHON_MODULE(my_module)
    {
        class_<Bar>("Bar");
        def_void_function("b1", b1);
        def_void_function("b2", b2);
        def_void_function("b3", b3);
    }

Python code:

    >>> from my_module import *
    >>> b = b1() # each of these calls
    >>> b = b2() # creates a brand
    >>> b = b3() # new Bar object

### boost/python/return_opaque_pointer.hpp

#### Class `return_opaqe_pointer`

return_opaque_pointer is a model of ResultConverterGenerator which can be used to wrap C++ functions returning pointers to undefined types such that the return value is copied into a new Python object.

In addition to specifying the `return_opaque_pointer` policy the `BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID` macro must be used to define specializations for the `type_id` function on the type pointed to by returned pointer.

    namespace boost { namespace python
    {
        struct return_opaque_pointer
        {
            template <class R> struct apply;
        };
    }}

#### Class `return_opaque_pointer` metafunctions

    template <class T> struct apply

Returns

  `detail::opaque_conversion_holder<R> type;`

#### Example

In C++:

    # include <boost/python/return_opaque_pointer.hpp>
    # include <boost/python/def.hpp>
    # include <boost/python/module.hpp>
    # include <boost/python/return_value_policy.hpp>

    typedef struct opaque_ *opaque;

    opaque the_op   = ((opaque) 0x47110815);

    opaque get () { return the_op; }
    void use (opaque op) {
        if (op != the_op)
    	throw std::runtime_error (std::string ("failed"));
    }

    void failuse (opaque op) {
        if (op == the_op)
    	throw std::runtime_error (std::string ("success"));
    }

    BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(opaque_)

    namespace bpl = boost::python;

    BOOST_PYTHON_MODULE(opaque_ext)
    {
        bpl::def (
            "get", &::get, bpl::return_value_policy<bpl::return_opaque_pointer>());
        bpl::def ("use", &::use);
        bpl::def ("failuse", &::failuse);
    }

Python code:

    """
    >>> from opaque_ext import *
    >>> #
    >>> # Check for correct conversion
    >>> use(get())
    >>> failuse(get())
    Traceback (most recent call last):
            ...
    RuntimeError: success
    >>> #
    >>> # Check that there is no conversion from integers ...
    >>> use(0)
    Traceback (most recent call last):
            ...
    TypeError: bad argument type for built-in operation
    >>> #
    >>> # ... and from strings to opaque objects
    >>> use("")
    Traceback (most recent call last):
            ...
    TypeError: bad argument type for built-in operation
    """
    def run(args = None):
        import sys
        import doctest

        if args is not None:
            sys.argv = args
        return doctest.testmod(sys.modules.get(__name__))

    if __name__ == '__main__':
        print "running..."
        import sys
        sys.exit(run()[0])