trunk/Examples/java/pointer/index.html - third_party/swig - Git at Google

 <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="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 cpointer.i library files can be
 found in the SWIG user manual.  The files also contain documentation.

 </ul>

 <hr>
 </body>
 </html>
	<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="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 cpointer.i library files can be
	found in the SWIG user manual. The files also contain documentation.

	</ul>

	<hr>
	</body>
	</html>