SWIG:Examples:ruby:reference

`SWIG/Examples/ruby/reference/`

## C++ Reference Handling

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.

## Some examples

References are most commonly used as function parameter. For example, you might have an operator like this:

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

or a function:

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

In these cases, SWIG transforms everything into a pointer and creates a wrapper that looks like this:

>     Vector wrap_addv(Vector *a, Vector *b) {
>         return addv(*a,*b);
>     }

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:

>     Vector &operator[](int index);

or a method:

>     Vector &get(int index);

For functions returning references, a wrapper like this is created:

>     Vector *wrap_Object_get(Object *self, int index) {
>         Vector &result = self->get(index);
>         return &result;
>     }

The following header file contains some class definitions with some operators and use of references.

## SWIG Interface

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 `addv()` function above. Array access can be handled with a pair of set/get functions like this:

>     class VectorArray {
>     public:
>      ...
>        %addmethods {
>         Vector &get(int index) {
>           return (*self)[index];
>         }
>         void set(int index, Vector &a) {
>           (*self)[index] = a;
>         }
>        }
>        ...
>     }

Click here to see a SWIG interface file with these additions.

## Sample Ruby script

Click here to see a script that manipulates some C++ references.

## Notes:

- C++ references primarily provide notational convenience for C++ source code. However, Ruby only supports the 'x.a' notation so it doesn't much matter.

- When a program returns a reference, a pointer is returned. Unlike return by value, memory is not allocated to hold the return result.

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