PageRenderTime 21ms CodeModel.GetById 19ms app.highlight 1ms RepoModel.GetById 0ms app.codeStats 0ms

/tags/rel-1-3-26/SWIG/Examples/tcl/reference/index.html

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