<html> <head> <title>SWIG:Examples:java:pointer</title> </head> <body bgcolor="#ffffff"> <tt>SWIG/Examples/java/pointer/</tt> <hr> <H2>Simple Pointer Handling</H2> <tt>$Header: /cvs/projects/SWIG/Examples/java/pointer/Attic/index.html,v 1.1.2.1 2002/01/27 00:41:27 cheetah Exp $</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 Java program? <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> By default SWIG wraps a C pointer with a Java long. Now in a Java program you would do this: <blockquote> <pre> long a = new_int(37); long b = new_int(42); long c = new_int(0); add(a,b,c); int r = get_int(c); System.out.println("Result =" + r); delete_int(a); delete_int(b); delete_int(c); </pre> </blockquote> <p> <li>Use the SWIG pointer library. [Sorry, but the Java module has not yet implemented this.] <br> For example, in the interface file you would do this: <blockquote> <pre> %include "pointer.i" </pre> </blockquote? and from Java you would do this: <blockquote> <pre> String a = ptrcreate("int",37); String b = ptrcreate("int",42); String c = ptrcreate("int"); add(a,b,c); int r = ptrvalue(c); System.out.println("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 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. <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="main.java">main.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 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>