ceph/src/boost/libs/python/doc/reference/overloads.qbk

   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]