doc/return_reference_to.rst

   1 return_reference_to
   2 -------------------
   3
   4 Motivation
   5 ~~~~~~~~~~
   6
   7 It is very common to return references to arguments or the this-pointer to
   8 allow for chaining in C++.
   9
  10 ::
  11
  12     struct A
  13     {
  14         float val;
  15
  16         A& set(float v)
  17         {
  18             val = v;
  19             return *this;
  20         }
  21     };
  22
  23 When luabind generates code for this, it will create a new object for the
  24 return-value, pointing to the self-object. This isn't a problem, but could be a
  25 bit inefficient. When using the return_reference_to-policy we have the ability
  26 to tell luabind that the return-value is already on the lua stack.
  27
  28 Defined in
  29 ~~~~~~~~~~
  30
  31 .. parsed-literal::
  32
  33     #include <luabind/return_reference_to_policy.hpp>
  34
  35 Synopsis
  36 ~~~~~~~~
  37
  38 .. parsed-literal::
  39
  40     return_reference_to(index)
  41
  42 Parameters
  43 ~~~~~~~~~~
  44
  45 ========= =============================================================
  46 Parameter Purpose
  47 ========= =============================================================
  48 ``index`` The argument index to return a reference to, any argument but
  49           not ``result``.
  50 ========= =============================================================
  51
  52 Example
  53 ~~~~~~~
  54
  55 .. parsed-literal::
  56
  57     struct A
  58     {
  59         float val;
  60
  61         A& set(float v)
  62         {
  63             val = v;
  64             return \*this;
  65         }
  66     };
  67
  68     module(L)
  69     [
  70         class_<A>("A")
  71             .def(constructor<>())
  72             .def("set", &A::set, **return_reference_to(_1)**)
  73     ];
  74
  75 .. warning::
  76    This policy ignores all type information and should be used only it
  77    situations where the parameter type is a perfect match to the
  78    return-type (such as in the example).
  79