| <html> |
| <head> |
| <title>SWIG:Examples:tcl:pointer</title> |
| </head> |
| |
| <body bgcolor="#ffffff"> |
| |
| <tt>SWIG/Examples/tcl/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. The only |
| problem is how does one go about creating these objects from a script? |
| |
| <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> |
| |
| Now, in a script you would do this: |
| |
| <blockquote> |
| <pre> |
| set a [new_int 37] |
| set b [new_int 42] |
| set c [new_int 0] |
| add $a $b $c |
| set r [get_int $c] |
| puts "Result = $r" |
| delete_int $a |
| delete_int $b |
| delete_int $c |
| </pre> |
| </blockquote> |
| |
| <p> |
| <li>Use the SWIG pointer library. For example, in the interface file |
| you would do this: |
| |
| <blockquote> |
| <pre> |
| %include "pointer.i" |
| </pre> |
| </blockquote? |
| |
| and in a script you would do this: |
| |
| <blockquote> |
| <pre> |
| set a [ptrcreate int 37] |
| set b [ptrcreate int 42] |
| set c [ptrcreate int] |
| add $a $b $c |
| set r [ptrvalue $c] |
| puts "Result = $r" |
| ptrfree $a |
| ptrfree $b |
| ptrfree $c |
| </pre> |
| </blockquote> |
| |
| The advantage to using the pointer library is that it unifies some of the helper |
| functions behind a common set of names. For example, the same set of functions work |
| with int, double, float, and other fundamental types. |
| |
| <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 script: |
| |
| <blockquote> |
| <pre> |
| set r [add 37 42] |
| puts "Result = $r" |
| </pre> |
| </blockquote> |
| Needless to say, this is substantially easier. |
| |
| <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="runme.tcl">runme.tcl</a> (Tcl Script) |
| </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 pointer.i library files can be |
| found in the SWIG user manual. The files also contain documentation. |
| |
| <p> |
| <li>The pointer.i library is designed primarily for convenience. If you |
| are concerned about performance, you probably want to use a different |
| approach. |
| |
| </ul> |
| |
| <hr> |
| </body> |
| </html> |