Examples/ruby/reference/index.html

   1 <html>
   2 <head>
   3 <title>SWIG:Examples:ruby:reference</title>
   4 </head>
   5
   6 <body bgcolor="#ffffff">
   7
   8
   9 <tt>SWIG/Examples/ruby/reference/</tt>
  10 <hr>
  11
  12 <H2>C++ Reference Handling</H2>
  13
  14 <p>
  15 This example tests SWIG's handling of C++ references.  Since C++
  16 references are closely related to pointers (as both refer to a
  17 location in memory), SWIG simply collapses all references into
  18 pointers when creating wrappers.
  19
  20 <h2>Some examples</h2>
  21
  22 References are most commonly used as function parameter.  For example,
  23 you might have an operator like this:
  24
  25 <blockquote>
  26 <pre>
  27 Vector operator+(const Vector &amp;a, const Vector &amp;b) {
  28    Vector result;
  29    result.x = a.x + b.x;
  30    result.y = a.y + b.y;
  31    result.z = a.z + b.z;
  32    return result;
  33 }
  34 </pre>
  35 </blockquote>
  36
  37 or a function:
  38
  39 <blockquote>
  40 <pre>
  41 Vector addv(const Vector &amp;a, const Vector &amp;b) {
  42    Vector result;
  43    result.x = a.x + b.x;
  44    result.y = a.y + b.y;
  45    result.z = a.z + b.z;
  46    return result;
  47 }
  48 </pre>
  49 </blockquote>
  50
  51 In these cases, SWIG transforms everything into a pointer and creates a wrapper
  52 that looks like this:
  53
  54 <blockquote>
  55 <pre>
  56 Vector wrap_addv(Vector *a, Vector *b) {
  57     return addv(*a,*b);
  58 }
  59 </pre>
  60 </blockquote>
  61
  62 Occasionally, a reference is used as a return value of a function
  63 when the return result is to be used as an lvalue in an expression.
  64 The prototypical example is an operator like this:
  65
  66 <blockquote>
  67 <pre>
  68 Vector &amp;operator[](int index);
  69 </pre>
  70 </blockquote>
  71
  72 or a method:
  73
  74 <blockquote>
  75 <pre>
  76 Vector &amp;get(int index);
  77 </pre>
  78 </blockquote>
  79
  80 For functions returning references, a wrapper like this is created:
  81
  82 <blockquote>
  83 <pre>
  84 Vector *wrap_Object_get(Object *self, int index) {
  85     Vector &amp;result = self-&gt;get(index);
  86     return &amp;result;
  87 }
  88 </pre>
  89 </blockquote>
  90
  91 The following <a href="example.h">header file</a> contains some class
  92 definitions with some operators and use of references.
  93
  94 <h2>SWIG Interface</h2>
  95
  96 SWIG does NOT support overloaded operators so it can not directly build
  97 an interface to the classes in the above file.   However, a number of workarounds
  98 can be made.  For example, an overloaded operator can be stuck behind a function
  99 call such as the <tt>addv()</tt> function above.  Array access can be handled
 100 with a pair of set/get functions like this:
 101
 102 <blockquote>
 103 <pre>
 104 class VectorArray {
 105 public:
 106  ...
 107    %addmethods {
 108     Vector &amp;get(int index) {
 109       return (*self)[index];
 110     }
 111     void set(int index, Vector &amp;a) {
 112       (*self)[index] = a;
 113     }
 114    }
 115    ...
 116 }
 117 </pre>
 118 </blockquote>
 119
 120 Click <a href="example.i">here</a> to see a SWIG interface file with these additions.
 121
 122 <h2>Sample Ruby script</h2>
 123
 124 Click <a href="runme.rb">here</a> to see a script that manipulates some C++ references.
 125
 126 <h2>Notes:</h2>
 127
 128 <ul>
 129 <li>C++ references primarily provide notational convenience for C++
 130 source code.  However, Ruby only supports the 'x.a'
 131 notation so it doesn't much matter.
 132
 133 <p>
 134 <li>When a program returns a reference, a pointer is returned.
 135 Unlike return by value, memory is not allocated to hold the
 136 return result.
 137
 138 <p>
 139 <li>SWIG has particular trouble handling various combinations of references
 140 and pointers.  This is side effect of an old parsing scheme and
 141 type representation that will be replaced in future versions.
 142
 143 </ul>
 144
 145 <hr>
 146 </body>
 147 </html>