]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [section boost/python/overloads.hpp] |
2 | [section Introduction] | |
3 | 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 | |
4 | [section overload-dispatch-expressions] | |
5 | 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: | |
6 | [variablelist | |
7 | [[docstring][An [link ntbs] whose value will bound to the methods' `__doc__` attribute]] | |
8 | [[keywords][A [link function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions keyword-expression] which will be used to name (a trailing subsequence of) the arguments to the generated methods.]] | |
9 | [[call policies][An instance of some type which models CallPolicies.]] | |
10 | [[minimum arity][The minimum number of arguments to be accepted by a generated method overload.]] | |
11 | [[maximum arity][The maximum number of arguments to be accepted by a generated method overload.]] | |
12 | ] | |
13 | [endsect] | |
14 | [endsect] | |
15 | [section OverloadDispatcher Concept] | |
16 | 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. | |
17 | `` | |
18 | X() | |
19 | X(docstring) | |
20 | X(docstring, keywords) | |
21 | X(keywords, docstring) | |
22 | X()[policies] | |
23 | X(docstring)[policies] | |
24 | X(docstring, keywords)[policies] | |
25 | X(keywords, docstring)[policies] | |
26 | `` | |
27 | * If policies are supplied, it must be an instance of a type which models [link concepts.callpolicies CallPolicies], and will be used as the result's call policies. Otherwise the result's call policies will be an instance of [link function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici `default_call_policies`]. | |
28 | * If docstring is supplied it must be an [link ntbs], and will be used as the result's docstring. Otherwise the result has an empty docstring. | |
29 | * If keywords is supplied it must be the result of a [link function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions 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. | |
30 | [endsect] | |
31 | [section Macros] | |
32 | `` | |
33 | BOOST_PYTHON_FUNCTION_OVERLOADS(name, func_id, min_args, max_args) | |
34 | `` | |
35 | Expands to the definition of an OverloadDispatcher called name in the current scope which can be used to generate the following function invocation: | |
36 | ``func_id(a1, a2,...ai);`` | |
37 | for all `min_args <= i <= max_args`. | |
38 | `` | |
39 | BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(name, member_name, min_args, max_args) | |
40 | `` | |
41 | Expands to the definition of an OverloadDispatcher called name in the current scope which can be used to generate the following function invocation: | |
42 | ``x.member_name(a1, a2,...ai);`` | |
43 | for all min_args <= i <= max_args, where x is a reference to an object of class type. | |
44 | [endsect] | |
45 | [section Example] | |
46 | `` | |
47 | #include <boost/python/module.hpp> | |
48 | #include <boost/python/def.hpp> | |
49 | #include <boost/python/args.hpp> | |
50 | #include <boost/python/tuple.hpp> | |
51 | #include <boost/python/class.hpp> | |
52 | #include <boost/python/overloads.hpp> | |
53 | #include <boost/python/return_internal_reference.hpp> | |
54 | ||
55 | using namespace boost::python; | |
56 | ||
57 | tuple f(int x = 1, double y = 4.25, char const* z = "wow") | |
58 | { | |
59 | return make_tuple(x, y, z); | |
60 | } | |
61 | ||
62 | BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3) | |
63 | ||
64 | struct Y {}; | |
65 | struct X | |
66 | { | |
67 | Y& f(int x, double y = 4.25, char const* z = "wow") | |
68 | { | |
69 | return inner; | |
70 | } | |
71 | Y inner; | |
72 | }; | |
73 | ||
74 | BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(f_member_overloads, f, 1, 3) | |
75 | ||
76 | BOOST_PYTHON_MODULE(args_ext) | |
77 | { | |
78 | def("f", f, | |
79 | f_overloads( | |
80 | args("x", "y", "z"), "This is f's docstring" | |
81 | )); | |
82 | ||
83 | ||
84 | class_<Y>("Y") | |
85 | ; | |
86 | ||
87 | class_<X>("X", "This is X's docstring") | |
88 | .def("f1", &X::f, | |
89 | f_member_overloads( | |
90 | args("x", "y", "z"), "f's docstring" | |
91 | )[return_internal_reference<>()] | |
92 | ) | |
93 | ; | |
94 | } | |
95 | `` | |
96 | [endsect] | |
97 | [endsect] |