/tags/rel-1-3-29/SWIG/Examples/java/pointer/index.html
HTML | 167 lines | 131 code | 36 blank | 0 comment | 0 complexity | 7392e5dc351e8e7c126b8c9afda815b9 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
1<html> 2<head> 3<title>SWIG:Examples:java:pointer</title> 4</head> 5 6<body bgcolor="#ffffff"> 7 8<tt>SWIG/Examples/java/pointer/</tt> 9<hr> 10 11<H2>Simple Pointer Handling</H2> 12 13<tt>$Header$</tt><br> 14 15<p> 16This example illustrates a couple of techniques for handling 17simple pointers in SWIG. The prototypical example is a C function 18that operates on pointers such as this: 19 20<blockquote> 21<pre> 22void add(int *x, int *y, int *r) { 23 *r = *x + *y; 24} 25</pre> 26</blockquote> 27 28By default, SWIG wraps this function exactly as specified and creates 29an interface that expects pointer objects for arguments. 30SWIG wraps a C pointer with a type wrapper class, for example, SWIGTYPE_p_int for an int*. 31The only problem is how does one go about creating these objects from a Java program? 32<p> 33 34 35<h2>Possible Solutions</h2> 36 37<ul> 38<li>Write some helper functions to explicitly create objects. For 39example: 40 41<blockquote> 42<pre> 43int *new_int(int ivalue) { 44 int *i = (int *) malloc(sizeof(ivalue)); 45 *i = ivalue; 46 return i; 47} 48int get_int(int *i) { 49 return *i; 50} 51 52void delete_int(int *i) { 53 free(i); 54} 55</pre> 56</blockquote> 57 58<p> 59<li>The SWIG pointer library provides an easier way. <br> 60For example, in the interface file 61you would do this: 62 63<blockquote> 64<pre> 65%include cpointer.i 66%pointer_functions(int, intp); 67</pre> 68</blockquote> 69 70and from Java you would use pointers like this: 71 72<blockquote> 73<pre> 74SWIGTYPE_p_int a = example.new_intp(); 75SWIGTYPE_p_int b = example.new_intp(); 76SWIGTYPE_p_int c = example.new_intp(); 77example.intp_assign(a,37); 78example.intp_assign(b,42); 79 80// Note that getCPtr() has package access by default 81System.out.println(" a =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(a))); 82System.out.println(" b =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(b))); 83System.out.println(" c =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(c))); 84 85// Call the add() function with some pointers 86example.add(a,b,c); 87 88// Now get the result 89int res = example.intp_value(c); 90System.out.println(" 37 + 42 =" + res); 91 92// Clean up the pointers 93example.delete_intp(a); 94example.delete_intp(b); 95example.delete_intp(c); 96</pre> 97</blockquote> 98 99<p> 100<li>Use the SWIG typemap library. This library allows you to completely 101change the way arguments are processed by SWIG. For example: 102 103<blockquote> 104<pre> 105%include "typemaps.i" 106void add(int *INPUT, int *INPUT, int *OUTPUT); 107</pre> 108</blockquote> 109 110And in a Java program: 111 112<blockquote> 113<pre> 114int[] r = {0}; 115example.sub(37,42,r); 116System.out.println("Result =" + r[0]); 117</pre> 118</blockquote> 119Needless to say, this is substantially easier although a bit unusual. 120 121<p> 122<li>A final alternative is to use the typemaps library in combination 123with the %apply directive. This allows you to change the names of parameters 124that behave as input or output parameters. For example: 125 126<blockquote> 127<pre> 128%include "typemaps.i" 129%apply int *INPUT {int *x, int *y}; 130%apply int *OUTPUT {int *r}; 131 132void add(int *x, int *y, int *r); 133void sub(int *x, int *y, int *r); 134void mul(int *x, int *y, int *r); 135... etc ... 136</pre> 137</blockquote> 138 139</ul> 140 141<h2>Example</h2> 142 143The following example illustrates the use of these features for pointer 144extraction. 145 146<ul> 147<li> <a href="example.c">example.c</a> (C Source) 148<li> <a href="example.i">example.i</a> (Swig interface) 149<li> <a href="main.java">main.java</a> (Java program) 150</ul> 151 152<h2>Notes</h2> 153 154<ul> 155<li>Since pointers are used for so many different things (arrays, output values, 156etc...) the complexity of pointer handling can be as complicated as you want to 157make it. 158 159<p> 160<li>More documentation on the typemaps.i and cpointer.i library files can be 161found in the SWIG user manual. The files also contain documentation. 162 163</ul> 164 165<hr> 166</body> 167</html>