C++ Boost

Boost.Python

Header <boost/python/overloads.hpp>

Contents

Introduction
overload-dispatch-expressions
OverloadDispatcher concept
Macros
BOOST_PYTHON_FUNCTION_OVERLOADS
BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
Example(s)

Introduction

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

overload-dispatch-expressions

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.

OverloadDispatcher Concept

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]

Macros

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.

Example(s)

#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<>()]
        )
        ;
}

Revised 15 April, 2003

© Copyright Dave Abrahams 2002.