<html>
<head>
<title>SWIG:Examples:java:pointer</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/java/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.
SWIG wraps a C pointer with a type wrapper class, for example, SWIGTYPE_p_int for an int*.
The only problem is how does one go about creating these objects from a Java program?
<p>
<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>
<p>
<li>The SWIG pointer library provides an easier way. <br>
For example, in the interface file
you would do this:
<blockquote>
<pre>
%include cpointer.i
%pointer_functions(int, intp);
</pre>
</blockquote>
and from Java you would use pointers like this:
<blockquote>
<pre>
SWIGTYPE_p_int a = example.new_intp();
SWIGTYPE_p_int b = example.new_intp();
SWIGTYPE_p_int c = example.new_intp();
example.intp_assign(a,37);
example.intp_assign(b,42);
// Note that getCPtr() has package access by default
System.out.println(" a =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(a)));
System.out.println(" b =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(b)));
System.out.println(" c =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(c)));
// Call the add() function with some pointers
example.add(a,b,c);
// Now get the result
int res = example.intp_value(c);
System.out.println(" 37 + 42 =" + res);
// Clean up the pointers
example.delete_intp(a);
example.delete_intp(b);
example.delete_intp(c);
</pre>
</blockquote>
<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 Java program:
<blockquote>
<pre>
int[] r = {0};
example.sub(37,42,r);
System.out.println("Result =" + r[0]);
</pre>
</blockquote>
Needless to say, this is substantially easier although a bit unusual.
<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.java">runme.java</a> (Java program)
</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 cpointer.i library files can be
found in the SWIG user manual. The files also contain documentation.
</ul>
<hr>
</body>
</html>