1 files changed, 171 insertions, 0 deletions
diff --git a/trunk/Examples/tcl/pointer/index.html b/trunk/Examples/tcl/pointer/index.html
new file mode 100644
index 000000000..407380240
--- /dev/null
+++ b/trunk/Examples/tcl/pointer/index.html
@@ -0,0 +1,171 @@
+<html>
+<head>
+<title>SWIG:Examples:tcl:pointer</title>
+</head>
+
+<body bgcolor="#ffffff">
+
+<tt>SWIG/Examples/tcl/pointer/</tt>
+<hr>
+
+<H2>Simple Pointer Handling</H2>
+
+<p>
+This example illustrates a couple of techniques for handling
+simple pointers in SWIG.  The prototypical example is a C function
+that operates on pointers such as this:
+
+<blockquote>
+<pre>
+void add(int *x, int *y, int *r) { 
+    *r = *x + *y;
+}
+</pre>
+</blockquote>
+
+By default, SWIG wraps this function exactly as specified and creates
+an interface that expects pointer objects for arguments.  The only
+problem is how does one go about creating these objects from a script?
+
+<h2>Possible Solutions</h2>
+
+<ul>
+<li>Write some helper functions to explicitly create objects.  For
+example:
+
+<blockquote>
+<pre>
+int *new_int(int ivalue) {
+  int *i = (int *) malloc(sizeof(ivalue));
+  *i = ivalue;
+  return i;
+}
+int get_int(int *i) {
+  return *i;
+}
+
+void delete_int(int *i) {
+  free(i);
+}
+</pre>
+</blockquote>
+
+Now, in a script you would do this:
+
+<blockquote>
+<pre>
+set a [new_int 37]
+set b [new_int 42]
+set c [new_int 0]
+add $a $b $c
+set r [get_int $c]
+puts "Result = $r"
+delete_int $a
+delete_int $b
+delete_int $c
+</pre>
+</blockquote>
+
+<p>
+<li>Use the SWIG pointer library.  For example, in the interface file 
+you would do this:
+
+<blockquote>
+<pre>
+%include "pointer.i"
+</pre>
+</blockquote?
+
+and in a script you would do this:
+
+<blockquote>
+<pre>
+set a [ptrcreate int 37]
+set b [ptrcreate int 42]
+set c [ptrcreate int]
+add $a $b $c
+set r [ptrvalue $c]
+puts "Result = $r"
+ptrfree $a
+ptrfree $b
+ptrfree $c
+</pre>
+</blockquote>
+
+The advantage to using the pointer library is that it unifies some of the helper
+functions behind a common set of names.  For example, the same set of functions work
+with int, double, float, and other fundamental types.
+
+<p>
+<li>Use the SWIG typemap library.  This library allows you to completely
+change the way arguments are processed by SWIG.  For example:
+
+<blockquote>
+<pre>
+%include "typemaps.i"
+void add(int *INPUT, int *INPUT, int *OUTPUT);
+</pre>
+</blockquote>
+
+And in a script:
+
+<blockquote>
+<pre>
+set r [add 37 42]
+puts "Result = $r"
+</pre>
+</blockquote>
+Needless to say, this is substantially easier.
+
+<p>
+<li>A final alternative is to use the typemaps library in combination
+with the %apply directive.  This allows you to change the names of parameters
+that behave as input or output parameters. For example:
+
+<blockquote>
+<pre>
+%include "typemaps.i"
+%apply int *INPUT {int *x, int *y};
+%apply int *OUTPUT {int *r};
+
+void add(int *x, int *y, int *r);
+void sub(int *x, int *y, int *r);
+void mul(int *x, int *y, int *r);
+... etc ...
+</pre>
+</blockquote>
+
+</ul>
+
+<h2>Example</h2>
+
+The following example illustrates the use of these features for pointer
+extraction.
+
+<ul>
+<li> <a href="example.c">example.c</a>  (C Source)
+<li> <a href="example.i">example.i</a>  (SWIG interface)
+<li> <a href="runme.tcl">runme.tcl</a> (Tcl Script)
+</ul>
+
+<h2>Notes</h2>
+
+<ul>
+<li>Since pointers are used for so many different things (arrays, output values,
+etc...) the complexity of pointer handling can be as complicated as you want to
+make it.
+
+<p>
+<li>More documentation on the typemaps.i and pointer.i library files can be
+found in the SWIG user manual.  The files also contain documentation.
+
+<p>
+<li>The pointer.i library is designed primarily for convenience.  If you
+are concerned about performance, you probably want to use a different
+approach.
+
+</ul>
+
+<hr>
+</body>
+</html>