SWIG:Examples:go:pointer

`SWIG/Examples/go/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. This only works when there is a precise correspondence between the C type and some Go type.

## Other approaches

- The SWIG pointer library provides a different, safer, way to handle pointers. For example, in the interface file you would do this:

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

  and from Go you would use pointers like this:

  >     a := example.New_intp()
  >     b := example.New_intp()
  >     c := example.New_intp()
  >     Intp_Assign(a, 37)
  >     Intp_Assign(b, 42)

  >     fmt.Println("     a =", a)
  >     fmt.Println("     b =", b)
  >     fmt.Println("     c =", c)

  >     // Call the add() function with some pointers
  >     example.Add(a,b,c)

  >     // Now get the result
  >     res := example.Intp_value(c)
  >     fmt.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 Go program:

  >     r := []int{0}
  >     example.Sub(37,42,r)
  >     fmt.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.go (Go 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.