/trunk/Examples/perl5/pointer/index.html
HTML | 171 lines | 137 code | 34 blank | 0 comment | 0 complexity | a03d82eab840c4027238ba132c816cce MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
- <html>
- <head>
- <title>SWIG:Examples:perl5:pointer</title>
- </head>
- <body bgcolor="#ffffff">
- <tt>SWIG/Examples/perl5/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>
- $a = new_int(37);
- $b = new_int(42);
- $c = new_int(0):
- add($a,$b,$c);
- $r = get_int($c);
- print "Result = $r\n";
- 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>
- $a = ptrcreate("int",37);
- $b = ptrcreate("int",42);
- $c = ptrcreate("int");
- add($a,$b,$c);
- $r = ptrvalue($c);
- print "Result = $r\n";
- 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>
- $r = add(37,42);
- print "Result = $r\n";
- </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 subtract(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.pl">runme.pl</a> (Perl 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>