PrevUpHomeNext

boost/python/overloads.hpp

Introduction
OverloadDispatcher Concept
Macros
Example

Defines facilities for generating families of overloaded Python functions and extension class methods from C++ functions and member functions with default arguments, or from similar families of C++ overloads

An overload-dispatch-expression is used to describe a family of overloaded methods to be generated for an extension class. It has the following properties:

docstring

An ntbs whose value will bound to the methods' __doc__ attribute

keywords

A keyword-expression which will be used to name (a trailing subsequence of) the arguments to the generated methods.

call policies

An instance of some type which models CallPolicies.

minimum arity

The minimum number of arguments to be accepted by a generated method overload.

maximum arity

The maximum number of arguments to be accepted by a generated method overload.

An OverloadDispatcher X is a class which has a minimum arity and a maximum arity, and for which the following following are valid overload-dispatch-expressions, with the same minimum and maximum arity as the OverloadDispatcher.

X()
X(docstring)
X(docstring, keywords)
X(keywords, docstring)
X()[policies]
X(docstring)[policies]
X(docstring, keywords)[policies]
X(keywords, docstring)[policies]

* If policies are supplied, it must be an instance of a type which models CallPolicies, and will be used as the result's call policies. Otherwise the result's call policies will be an instance of default_call_policies. * If docstring is supplied it must be an ntbs, and will be used as the result's docstring. Otherwise the result has an empty docstring. * If keywords is supplied it must be the result of a keyword-expression whose length is no greater than X's maximum arity, and will be used as the result's keywords. Otherwise the result's keywords will be empty.

BOOST_PYTHON_FUNCTION_OVERLOADS(name, func_id, min_args, max_args)

Expands to the definition of an OverloadDispatcher called name in the current scope which can be used to generate the following function invocation:

func_id(a1, a2,...ai);

for all min_args <= i <= max_args.

BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(name, member_name, min_args, max_args)

Expands to the definition of an OverloadDispatcher called name in the current scope which can be used to generate the following function invocation:

x.member_name(a1, a2,...ai);

for all min_args <= i <= max_args, where x is a reference to an object of class type.

#include <boost/python/module.hpp>
#include <boost/python/def.hpp>
#include <boost/python/args.hpp>
#include <boost/python/tuple.hpp>
#include <boost/python/class.hpp>
#include <boost/python/overloads.hpp>
#include <boost/python/return_internal_reference.hpp>

using namespace boost::python;

tuple f(int x = 1, double y = 4.25, char const* z = "wow")
{
    return make_tuple(x, y, z);
}

BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3)

struct Y {};
struct X
{
    Y& f(int x, double y = 4.25, char const* z = "wow")
    {
        return inner;
    }
    Y inner;
};

BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(f_member_overloads, f, 1, 3)

BOOST_PYTHON_MODULE(args_ext)
{
    def("f", f,
        f_overloads(
            args("x", "y", "z"), "This is f's docstring"
        ));


    class_<Y>("Y")
        ;

    class_<X>("X", "This is X's docstring")
        .def("f1", &X::f,
                f_member_overloads(
                    args("x", "y", "z"), "f's docstring"
                )[return_internal_reference<>()]
        )
        ;
}

PrevUpHomeNext