index.html | searchcode

/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>