mirror of https://github.com/swig/swig
144 lines
3.2 KiB
HTML
144 lines
3.2 KiB
HTML
<html>
|
|
<head>
|
|
<title>SWIG:Examples:go:reference</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
|
|
<tt>SWIG/Examples/go/reference/</tt>
|
|
<hr>
|
|
|
|
<H2>C++ Reference Handling</H2>
|
|
|
|
<p>
|
|
This example tests SWIG's handling of C++ references. A reference in
|
|
C++ is much like a pointer. Go represents C++ classes as pointers
|
|
which are stored in interface values. Therefore, a reference to a
|
|
class in C++ simply becomes an object of the class type in Go. For
|
|
types which are not classes, a reference in C++ is represented as a
|
|
pointer in Go.
|
|
|
|
<h2>Some examples</h2>
|
|
|
|
References are most commonly used as function parameters. For
|
|
example, you might have a function like this:
|
|
|
|
<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 in C++.
|
|
|
|
<blockquote>
|
|
<pre>
|
|
Vector wrap_addv(Vector *a, Vector *b);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
or like this in Go:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
func Addv(arg1 Vector, arg2 Vector) Vector
|
|
</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:
|
|
...
|
|
%extend {
|
|
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 Go program</h2>
|
|
|
|
Click <a href="runme.go">here</a> to see a Go program that manipulates
|
|
some C++ references.
|
|
|
|
<h2>Notes:</h2>
|
|
|
|
<ul>
|
|
<li>C++ references primarily provide notational convenience for C++
|
|
source code. However, Go 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>
|