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

   1 [section boost/python/make_function.hpp]
   2 [section Introduction]
   3 make_function() and make_constructor() are the functions used internally by def() and class_<>::def() to produce Python callable objects which wrap C++ functions and member functions.
   4 [endsect]
   5 [section Functions]
   6 ``
   7 template <class F>
   8 object make_function(F f)
   9
  10 template <class F, class Policies>
  11 object make_function(F f, Policies const& policies)
  12
  13 template <class F, class Policies, class KeywordsOrSignature>
  14 object make_function(F f, Policies const& policies, KeywordsOrSignature const& ks)
  15
  16 template <class F, class Policies, class Keywords, class Signature>
  17 object make_function(F f, Policies const& policies, Keywords const& kw, Signature const& sig)
  18 ``
  19 [variablelist
  20 [[Requires][F is a function pointer or member function pointer type. If policies are supplied, it must be a model of CallPolicies. If kewords are supplied, it must be the result of a keyword-expression specifying no more arguments than the arity of f.]]
  21 [[Effects][Creates a Python callable object which, when called from Python, converts its arguments to C++ and calls f. If F is a pointer-to-member-function type, the target object of the function call (*this) will be taken from the first Python argument, and subsequent Python arguments will be used as the arguments to f.
  22
  23 * If policies are supplied, it will be applied to the function as described here.
  24 * If keywords are supplied, the keywords will be applied in order to the final arguments of the resulting function.
  25 * If Signature is supplied, it should be an instance of an MPL front-extensible sequence representing the function's return type followed by its argument types. Pass a Signature when wrapping function object types whose signatures can't be deduced, or when you wish to override the types which will be passed to the wrapped function. ]]
  26 [[Returns][An instance of object which holds the new Python callable object.]]
  27 [[Caveats][An argument of pointer type may be 0 if None is passed from Python. An argument type which is a constant reference may refer to a temporary which was created from the Python object for just the duration of the call to the wrapped function, for example a std::vector conjured up by the conversion process from a Python list. Use a non-const reference argument when a persistent lvalue is required. ]]
  28 ]
  29 ``
  30 template <class F>
  31 object make_constructor(F f)
  32
  33 template <class F, class Policies>
  34 object make_constructor(F f, Policies const& policies)
  35
  36 template <class F, class Policies, class KeywordsOrSignature>
  37 object make_constructor(F f, Policies const& policies, KeywordsOrSignature const& ks)
  38
  39 template <class F, class Policies, class Keywords, class Signature>
  40 object make_constructor(F f, Policies const& policies, Keywords const& kw, Signature const& sig)
  41 ``
  42 [variablelist
  43 [[Requires][F is a function pointer type. If policies are supplied, it must be a model of CallPolicies. If kewords are supplied, it must be the result of a keyword-expression specifying no more arguments than the arity of f.]]
  44 [[Effects][Creates a Python callable object which, when called from Python, converts its arguments to C++ and calls f.]]
  45 [[Returns][An instance of object which holds the new Python callable object.]]
  46 ]
  47
  48 [endsect]
  49 [section Example]
  50 C++ function exposed below returns a callable object wrapping one of two functions.
  51 ``
  52 #include <boost/python/make_function.hpp>
  53 #include <boost/python/module.hpp>
  54
  55 char const* foo() { return "foo"; }
  56 char const* bar() { return "bar"; }
  57
  58 using namespace boost::python;
  59 object choose_function(bool selector)
  60 {
  61     if (selector)
  62         return boost::python::make_function(foo);
  63     else
  64         return boost::python::make_function(bar);
  65 }
  66
  67 BOOST_PYTHON_MODULE(make_function_test)
  68 {
  69     def("choose_function", choose_function);
  70 }
  71 ``
  72 It can be used this way in Python:
  73 ``
  74 >>> from make_function_test import *
  75 >>> f = choose_function(1)
  76 >>> g = choose_function(0)
  77 >>> f()
  78 'foo'
  79 >>> g()
  80 'bar'
  81 ``
  82 [endsect]
  83 [endsect]