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

   1 [section boost/python/init.hpp]
   2 [section Introduction]
   3 <boost/python/init.hpp> defines the interface for exposing C++ constructors to Python as extension class `__init__` functions.
   4 [section init-expressions]
   5 An init-expression is used to describe a family of `__init__` methods to be generated for an extension class, and the result has the following properties:
   6 [variablelist
   7 [[docstring][An [link ntbs] whose value will bound to the method's `__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 `__init__` function(s).]]
   9 [[call_policies][An instance of a model of [link concepts.callpolicies CallPolicies].]]
  10 [[argument_types][An MPL sequence of C++ argument types which will be used to construct the wrapped C++ object. An init expression has one or more valid prefixes which are given by a sequence of prefixes of its argument types.]]
  11 ]
  12 [endsect]
  13 [endsect]
  14 [section Class template `init`]
  15 A MPL sequence which can be used to specify a family of one or more __init__ functions. Only the last Ti supplied may be an instantiation of optional<...>.
  16
  17 ``
  18 namespace boost { namespace python
  19 {
  20   template <T1 = unspecified,...Tn = unspecified>
  21   struct init
  22   {
  23     init(char const* doc = 0);
  24     template <class Keywords> init(Keywords const& kw, char const* doc = 0);
  25     template <class Keywords> init(char const* doc, Keywords const& kw);
  26
  27     template <class CallPolicies>
  28     unspecified operator[](CallPolicies const& policies) const
  29   };
  30 }}
  31 ``
  32 [section Class template `init` constructors]
  33 ``
  34 init(char const* doc = 0);
  35 template <class Keywords> init(Keywords const& kw, char const* doc = 0);
  36 template <class Keywords> init(char const* doc, Keywords const& kw);
  37 ``
  38 [variablelist
  39 [[Requires][If supplied, doc is an [link ntbs]. If supplied, kw is the result of a ]]
  40 [[Effects][The result is an init-expression whose docstring is doc and whose keywords are a reference to kw. If the first form is used, the resulting expression's keywords are empty. The expression's call policies are an instance of [link function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici default_call_policies]. If Tn is [link high_level_components.boost_python_init_hpp.class_template_optional optional<U1, U2,... Um>], the expression's valid prefixes are given by: ``(T1, T2,...Tn-1), (T1, T2,...Tn-1 , U1), (T1, T2,...Tn-1 , U1, U2), ...(T1, T2,...Tn-1 , U1, U2,...Um)``.
  41 Otherwise, the expression has one valid prefix given by the template arguments the user specified. ]]
  42 ]
  43 [endsect]
  44 [section Class template `init` observer functions]
  45 ``
  46 template <class Policies>
  47 unspecified operator[](Policies const& policies) const
  48 ``
  49 [variablelist
  50 [[Requires][Policies is a model of [link concepts.callpolicies CallPolicies].]]
  51 [[Effects][Returns a new [link high_level_components.boost_python_init_hpp.introduction.init_expressions init-expression] with all the same properties as the init object except that its call policies are replaced by a reference to policies.]]
  52 ]
  53 [endsect]
  54 [endsect]
  55 [section Class template `optional` ]
  56 A MPL sequence which can be used to specify the optional arguments to an __init__ function.
  57 ``
  58 namespace boost { namespace python
  59 {
  60   template <T1 = unspecified,...Tn = unspecified>
  61   struct optional {};
  62 }}
  63 ``
  64 [endsect]
  65 [section Example]
  66 Given the C++ declarations:
  67 ``
  68 class Y;
  69 class X
  70 {
  71  public:
  72    X(int x, Y* y) : m_y(y) {}
  73    X(double);
  74  private:
  75    Y* m_y;
  76 };
  77 ``
  78 A corresponing Boost.Python extension class can be created with:
  79 ``
  80 using namespace boost::python;
  81
  82 class_<X>("X", "This is X's docstring.",
  83           init<int,char const*>(args("x","y"), "X.__init__'s docstring")[
  84                 with_custodian_and_ward<1,3>()]
  85           )
  86    .def(init<double>())
  87    ;
  88
  89 ``
  90 [endsect]
  91 [endsect]