`SWIG/Examples/java/pointer/`

## Simple Pointer Handling

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:

>     void add(int *x, int *y, int *r) {
>         *r = *x + *y;
>     }

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?

## Possible Solutions

- Write some helper functions to explicitly create objects. For example:

  >     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);
  >     }

- The SWIG pointer library provides an easier way.
  For example, in the interface file you would do this:

  >     %include cpointer.i
  >     %pointer_functions(int, intp);

  and from Java you would use pointers like this:

  >     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);

- Use the SWIG typemap library. This library allows you to completely change the way arguments are processed by SWIG. For example:

  >     %include "typemaps.i"
  >     void add(int *INPUT, int *INPUT, int *OUTPUT);

  And in a Java program:

  >     int[] r = {0};
  >     example.sub(37,42,r);
  >     System.out.println("Result =" + r[0]);

  Needless to say, this is substantially easier although a bit unusual.

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

  >     %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 ...

## Example

The following example illustrates the use of these features for pointer extraction.

- example.c (C Source)
- example.i (SWIG interface)
- runme.java (Java program)

## Notes

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

- More documentation on the typemaps.i and cpointer.i library files can be found in the SWIG user manual. The files also contain documentation.