| <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> |
