new example

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@789 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Examples/tcl/index.html

@@ -19,6 +19,7 @@ certain C declarations are turned into constants.
 <li><a href="variables/index.html">variables</a>.  How SWIG can be used to wrap C global variables.
 <li><a href="value/index.html">value</a>. How to pass and return structures by value.
 <li><a href="class/index.html">class</a>. How wrap a simple C++ class.
+<li><a href="reference/index.html">reference</a>. C++ references.
 </ul>
 
 <h2>Compilation Issues</h2>

Examples/tcl/reference/Makefile

@@ -0,0 +1,19 @@
+TOP        = ../..
+SWIG       = $(TOP)/../swig
+CXXSRCS    = example.cxx
+TARGET     = example
+INTERFACE  = example.i
+LIBS       = -lm
+
+all::
+	$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
+	TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' tcl_cpp
+
+static::
+	$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
+	TARGET='mytclsh' INTERFACE='$(INTERFACE)' tclsh_cpp_static
+
+clean::
+	rm -f *_wrap* *.o *~ *.so mytclsh *.pyc .~* core
+
+check: all

Examples/tcl/reference/example.cxx

@@ -0,0 +1,41 @@
+/* File : example.cxx */
+
+#include "example.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+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;
+}
+

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();
+};
+
+
+
+  

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

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

Examples/tcl/reference/index.html

@@ -0,0 +1,149 @@
+<html>
+<head>
+<title>SWIG:Examples:tcl:reference</title>
+</head>
+
+<body bgcolor="#ffffff">
+
+
+<tt>SWIG/Examples/tcl/reference/</tt>
+<hr>
+
+<H2>C++ Reference Handling</H2>
+
+<tt>$Header$</tt><br>
+
+<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 Tcl scripts</h2>
+
+Click <a href="example.tcl">here</a> to see a script that manipulates some C++ references.
+
+<h2>Notes:</h2>
+
+<ul>
+<li>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.
+
+<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>