/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
- <html>
- <head>
- <title>SWIG:Examples:java:reference</title>
- </head>
- <body bgcolor="#ffffff">
- <tt>SWIG/Examples/java/reference/</tt>
- <hr>
- <H2>C++ Reference Handling</H2>
- <p>
- This example tests SWIG's handling of C++ references. Since C++
- references are closely related to pointers (as both refer to a
- location in memory), SWIG simply collapses all references into
- pointers when creating wrappers.
- <h2>Some examples</h2>
- References are most commonly used as function parameter. For example,
- you might have an operator like this:
- <blockquote>
- <pre>
- Vector operator+(const Vector &a, const Vector &b) {
- Vector result;
- result.x = a.x + b.x;
- result.y = a.y + b.y;
- result.z = a.z + b.z;
- return result;
- }
- </pre>
- </blockquote>
- or a function:
- <blockquote>
- <pre>
- Vector addv(const Vector &a, const Vector &b) {
- Vector result;
- result.x = a.x + b.x;
- result.y = a.y + b.y;
- result.z = a.z + b.z;
- return result;
- }
- </pre>
- </blockquote>
- In these cases, SWIG transforms everything into a pointer and creates a wrapper
- that looks like this:
- <blockquote>
- <pre>
- Vector wrap_addv(Vector *a, Vector *b) {
- return addv(*a,*b);
- }
- </pre>
- </blockquote>
- Occasionally, a reference is used as a return value of a function
- when the return result is to be used as an lvalue in an expression.
- The prototypical example is an operator like this:
- <blockquote>
- <pre>
- Vector &operator[](int index);
- </pre>
- </blockquote>
- or a method:
- <blockquote>
- <pre>
- Vector &get(int index);
- </pre>
- </blockquote>
- For functions returning references, a wrapper like this is created:
- <blockquote>
- <pre>
- Vector *wrap_Object_get(Object *self, int index) {
- Vector &result = self->get(index);
- return &result;
- }
- </pre>
- </blockquote>
- The following <a href="example.h">header file</a> contains some class
- definitions with some operators and use of references.
- <h2>SWIG Interface</h2>
- SWIG does NOT support overloaded operators so it can not directly build
- an interface to the classes in the above file. However, a number of workarounds
- can be made. For example, an overloaded operator can be stuck behind a function
- call such as the <tt>addv()</tt> function above. Array access can be handled
- with a pair of set/get functions like this:
- <blockquote>
- <pre>
- class VectorArray {
- public:
- ...
- %addmethods {
- Vector &get(int index) {
- return (*self)[index];
- }
- void set(int index, Vector &a) {
- (*self)[index] = a;
- }
- }
- ...
- }
- </pre>
- </blockquote>
- Click <a href="example.i">here</a> to see a SWIG interface file with these additions.
- <h2>Sample Java program</h2>
- Click <a href="main.java">here</a> to see a Java program that manipulates some C++ references.
- <h2>Notes:</h2>
- <ul>
- <li>C++ references primarily provide notational convenience for C++
- source code. However, Java only supports the 'x.a'
- notation so it doesn't much matter.
- <p>
- <li>When a program returns a reference, a pointer is returned.
- Unlike return by value, memory is not allocated to hold the
- return result.
- <p>
- <li>SWIG has particular trouble handling various combinations of references
- and pointers. This is side effect of an old parsing scheme and
- type representation that will be replaced in future versions.
- </ul>
- <hr>
- </body>
- </html>