From 44f7039d7dd0bb4324d322304358b14802a72c3d Mon Sep 17 00:00:00 2001
From: Dave Beazley <dave-swig@dabeaz.com>
Date: Sat, 2 Sep 2000 19:26:03 +0000
Subject: [PATCH] new example

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@809 626c5289-ae23-0410-ae9c-e8d60b6d4f22
---
 Examples/python/index.html         |   1 +
 Examples/python/pointer/Makefile   |  18 +++
 Examples/python/pointer/example.c  |  16 +++
 Examples/python/pointer/example.i  |  23 ++++
 Examples/python/pointer/example.py |  42 +++++++
 Examples/python/pointer/index.html | 173 +++++++++++++++++++++++++++++
 6 files changed, 273 insertions(+)
 create mode 100644 Examples/python/pointer/Makefile
 create mode 100644 Examples/python/pointer/example.c
 create mode 100644 Examples/python/pointer/example.i
 create mode 100644 Examples/python/pointer/example.py
 create mode 100644 Examples/python/pointer/index.html

diff --git a/Examples/python/index.html b/Examples/python/index.html
index e3533de73..c11247421 100644
--- a/Examples/python/index.html
+++ b/Examples/python/index.html
@@ -20,6 +20,7 @@ certain C declarations are turned into constants.
 <li><a href="value/index.html">value</a>. How to pass and return structures by value.
 <li><a href="class/index.html">class</a>. Wrapping a simple C++ class.
 <li><a href="reference/index.html">reference</a>. C++ references.
+<li><a href="pointer/index.html">pointer</a>. Simple pointer handling.
 </ul>
 
 <h2>Compilation Issues</h2>
diff --git a/Examples/python/pointer/Makefile b/Examples/python/pointer/Makefile
new file mode 100644
index 000000000..e495cfa9a
--- /dev/null
+++ b/Examples/python/pointer/Makefile
@@ -0,0 +1,18 @@
+TOP        = ../..
+SWIG       = $(TOP)/../swig
+SRCS       = example.c
+TARGET     = example
+INTERFACE  = example.i
+
+all::
+	$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
+	TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' python
+
+static::
+	$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
+	TARGET='mypython' INTERFACE='$(INTERFACE)' python_static
+
+clean::
+	rm -f *_wrap* *.o *~ *.so mypython *.pyc .~* core
+
+check: all
diff --git a/Examples/python/pointer/example.c b/Examples/python/pointer/example.c
new file mode 100644
index 000000000..b877d9a5b
--- /dev/null
+++ b/Examples/python/pointer/example.c
@@ -0,0 +1,16 @@
+/* File : example.c */
+
+void add(int *x, int *y, int *result) {
+  *result = *x + *y;
+}
+
+void sub(int *x, int *y, int *result) {
+  *result = *x - *y;
+}
+
+int divide(int n, int d, int *r) {
+   int q;
+   q = n/d;
+   *r = n - q*d;
+   return q;
+}
diff --git a/Examples/python/pointer/example.i b/Examples/python/pointer/example.i
new file mode 100644
index 000000000..2ed2b5bbf
--- /dev/null
+++ b/Examples/python/pointer/example.i
@@ -0,0 +1,23 @@
+/* File : example.i */
+%module example
+
+/* This example illustrates a couple of different techniques
+   for manipulating C pointers */
+
+/* First we'll use the pointer library */
+extern void add(int *x, int *y, int *result);
+%include pointer.i
+
+/* Next we'll use some typemaps */
+
+%include typemaps.i
+extern void sub(int *INPUT, int *INPUT, int *OUTPUT);
+
+/* Next we'll use typemaps and the %apply directive */
+
+%apply int *OUTPUT { int *r };
+extern int divide(int n, int d, int *r);
+
+
+
+
diff --git a/Examples/python/pointer/example.py b/Examples/python/pointer/example.py
new file mode 100644
index 000000000..c7363ab3a
--- /dev/null
+++ b/Examples/python/pointer/example.py
@@ -0,0 +1,42 @@
+# file: example.py
+
+import example;
+
+# First create some objects using the pointer library.
+print "Testing the pointer library";
+a = example.ptrcreate("int",37);
+b = example.ptrcreate("int",42);
+c = example.ptrcreate("int");  
+
+print "     a =",a
+print "     b =",b
+print "     c =",c
+
+# Call the add() function with some pointers
+example.add(a,b,c)
+
+# Now get the result
+r = example.ptrvalue(c)
+print "     37 + 42 =",r
+
+# Clean up the pointers
+example.ptrfree(a)
+example.ptrfree(b)
+example.ptrfree(c)
+
+# Now try the typemap library
+# This should be much easier. Now how it is no longer
+# necessary to manufacture pointers.
+
+print "Trying the typemap library";
+r = example.sub(37,42)
+print "     37 - 42 =",r
+
+# Now try the version with multiple return values
+
+print "Testing multiple return values";
+q,r = example.divide(42,37)
+print "     42/37 = %d remainder %d" % (q,r)
+
+
+
diff --git a/Examples/python/pointer/index.html b/Examples/python/pointer/index.html
new file mode 100644
index 000000000..a18fbfb8f
--- /dev/null
+++ b/Examples/python/pointer/index.html
@@ -0,0 +1,173 @@
+<html>
+<head>
+<title>SWIG:Examples:python:pointer</title>
+</head>
+
+<body bgcolor="#ffffff">
+
+<tt>SWIG/Examples/python/pointer/</tt>
+<hr>
+
+<H2>Simple Pointer Handling</H2>
+
+<tt>$Header$</tt><br>
+
+<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>
+a = new_int(37)
+b = new_int(42)
+c = new_int(0)
+add(a,b,c)
+r = get_int(c);
+print "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>
+a = ptrcreate("int",37)
+b = ptrcreate("int",42)
+c = ptrcreate("int")
+add(a,b,c)
+r = ptrvalue(c)
+print "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>
+r = add(37,42)
+print "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="example.py">example.py</a> (Python 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>