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