PageRenderTime 20ms CodeModel.GetById 13ms app.highlight 6ms RepoModel.GetById 0ms app.codeStats 0ms

/tags/rel-1.3.35/Examples/java/reference/index.html

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