+
+Vector operator+(const Vector &a, const Vector &b) {
+ Vector r;
+ r.x = a.x + b.x;
+ r.y = a.y + b.y;
+ r.z = a.z + b.z;
+ return r;
+}
+
+char *Vector::print() {
+ static char temp[512];
+ sprintf(temp,"Vector %x (%g,%g,%g)", this, x,y,z);
+ return temp;
+}
+
+VectorArray::VectorArray(int size) {
+ items = new Vector[size];
+ maxsize = size;
+}
+
+VectorArray::~VectorArray() {
+ delete [] items;
+}
+
+Vector &VectorArray::operator[](int index) {
+ if ((index < 0) || (index >= maxsize)) {
+ printf("Panic! Array index out of bounds.\n");
+ exit(1);
+ }
+ return items[index];
+}
+
+int VectorArray::size() {
+ return maxsize;
+}
+
diff --git a/Examples/tcl/reference/example.h b/Examples/tcl/reference/example.h
new file mode 100644
index 000000000..4915adb1b
--- /dev/null
+++ b/Examples/tcl/reference/example.h
@@ -0,0 +1,26 @@
+/* File : example.h */
+
+class Vector {
+private:
+ double x,y,z;
+public:
+ Vector() : x(0), y(0), z(0) { };
+ Vector(double x, double y, double z) : x(x), y(y), z(z) { };
+ friend Vector operator+(const Vector &a, const Vector &b);
+ char *print();
+};
+
+class VectorArray {
+private:
+ Vector *items;
+ int maxsize;
+public:
+ VectorArray(int maxsize);
+ ~VectorArray();
+ Vector &operator[](int);
+ int size();
+};
+
+
+
+
diff --git a/Examples/tcl/reference/example.i b/Examples/tcl/reference/example.i
new file mode 100644
index 000000000..8538326f6
--- /dev/null
+++ b/Examples/tcl/reference/example.i
@@ -0,0 +1,46 @@
+/* File : example.i */
+
+/* This file has a few "typical" uses of C++ references. */
+
+%module example
+
+%{
+#include "example.h"
+%}
+
+class Vector {
+public:
+ Vector(double x, double y, double z);
+ ~Vector();
+ char *print();
+};
+
+/* This helper function calls an overloaded operator */
+%inline %{
+Vector addv(Vector &a, Vector &b) {
+ return a+b;
+}
+%}
+
+/* Wrapper around an array of vectors class */
+
+class VectorArray {
+public:
+ VectorArray(int maxsize);
+ ~VectorArray();
+ int size();
+
+ /* This wrapper provides an alternative to the [] operator */
+ %addmethods {
+ Vector &get(int index) {
+ return (*self)[index];
+ }
+ void set(int index, Vector &a) {
+ (*self)[index] = a;
+ }
+ }
+};
+
+
+
+
diff --git a/Examples/tcl/reference/example.tcl b/Examples/tcl/reference/example.tcl
new file mode 100644
index 000000000..e21bc8541
--- /dev/null
+++ b/Examples/tcl/reference/example.tcl
@@ -0,0 +1,77 @@
+# file: example.tcl
+
+# This file illustrates the manipulation of C++ references in Tcl
+
+catch { load ./example.so example}
+catch { load ./example.dll example} ;# Windows
+
+# ----- Object creation -----
+
+puts "Creating some objects:"
+set a [new_Vector 3 4 5]
+set b [new_Vector 10 11 12]
+
+puts " Created [Vector_print $a]"
+puts " Created [Vector_print $b]"
+
+# ----- Call an overloaded operator -----
+
+# This calls the wrapper we placed around
+#
+# operator+(const Vector &a, const Vector &)
+#
+# It returns a new allocated object.
+
+puts "Adding a+b"
+set c [addv $a $b]
+puts " a+b = [Vector_print $c]"
+
+# Note: Unless we free the result, a memory leak will occur
+delete_Vector $c
+
+# ----- Create a vector array -----
+
+# Note: Using the high-level interface here
+puts "Creating an array of vectors"
+VectorArray va 10
+puts " va = [va cget -this]"
+
+
+# ----- Set some values in the array -----
+
+# These operators copy the value of $a and $b to the vector array
+va set 0 $a
+va set 1 $b
+
+# This will work, but it will cause a memory leak!
+
+va set 2 [addv $a $b]
+
+# The non-leaky way to do it
+
+set c [addv $a $b]
+va set 3 $c
+delete_Vector $c
+
+# Get some values from the array
+
+puts "Getting some array values"
+for {set i 0} {$i < 5} {incr i 1} {
+ puts " va($i) = [Vector_print [va get $i]]"
+}
+
+# Watch under resource meter to check on this
+puts "Making sure we don't leak memory."
+for {set i 0} {$i < 1000000} {incr i 1} {
+ set c [va get [expr {$i % 10}]]
+}
+
+# ----- Clean up -----
+puts "Cleaning up"
+
+rename va ""
+
+delete_Vector $a
+delete_Vector $b
+
+
diff --git a/Examples/tcl/reference/index.html b/Examples/tcl/reference/index.html
new file mode 100644
index 000000000..b941b1e9d
--- /dev/null
+++ b/Examples/tcl/reference/index.html
@@ -0,0 +1,149 @@
+
+
+SWIG:Examples:tcl:reference
+
+
+
+
+
+SWIG/Examples/tcl/reference/
+
+
+C++ Reference Handling
+
+$Header$
+
+
+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 Tcl scripts
+
+Click here to see a script that manipulates some C++ references.
+
+Notes:
+
+
+- C++ references primarily provide notational convenience for C++
+source code. However, Tcl has neither the 'x.a' or '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.
+
+
+
+
+
+