/trunk/Examples/python/pointer/index.html
HTML | 171 lines | 137 code | 34 blank | 0 comment | 0 complexity | c125f91aa3cc78fc3e244d781e945ae5 MD5 | raw file
1<html> 2<head> 3<title>SWIG:Examples:python:pointer</title> 4</head> 5 6<body bgcolor="#ffffff"> 7 8<tt>SWIG/Examples/python/pointer/</tt> 9<hr> 10 11<H2>Simple Pointer Handling</H2> 12 13<p> 14This example illustrates a couple of techniques for handling 15simple pointers in SWIG. The prototypical example is a C function 16that operates on pointers such as this: 17 18<blockquote> 19<pre> 20void add(int *x, int *y, int *r) { 21 *r = *x + *y; 22} 23</pre> 24</blockquote> 25 26By default, SWIG wraps this function exactly as specified and creates 27an interface that expects pointer objects for arguments. The only 28problem is how does one go about creating these objects from a script? 29 30<h2>Possible Solutions</h2> 31 32<ul> 33<li>Write some helper functions to explicitly create objects. For 34example: 35 36<blockquote> 37<pre> 38int *new_int(int ivalue) { 39 int *i = (int *) malloc(sizeof(ivalue)); 40 *i = ivalue; 41 return i; 42} 43int get_int(int *i) { 44 return *i; 45} 46 47void delete_int(int *i) { 48 free(i); 49} 50</pre> 51</blockquote> 52 53Now, in a script you would do this: 54 55<blockquote> 56<pre> 57a = new_int(37) 58b = new_int(42) 59c = new_int(0) 60add(a,b,c) 61r = get_int(c); 62print "Result =",r 63delete_int(a) 64delete_int(b) 65delete_int(c) 66</pre> 67</blockquote> 68 69<p> 70<li>Use the SWIG pointer library. For example, in the interface file 71you would do this: 72 73<blockquote> 74<pre> 75%include "pointer.i" 76</pre> 77</blockquote? 78 79and in a script you would do this: 80 81<blockquote> 82<pre> 83a = ptrcreate("int",37) 84b = ptrcreate("int",42) 85c = ptrcreate("int") 86add(a,b,c) 87r = ptrvalue(c) 88print "Result =",r 89ptrfree(a) 90ptrfree(b) 91ptrfree(c) 92</pre> 93</blockquote> 94 95The advantage to using the pointer library is that it unifies some of the helper 96functions behind a common set of names. For example, the same set of functions work 97with int, double, float, and other fundamental types. 98 99<p> 100<li>Use the SWIG typemap library. This library allows you to completely 101change the way arguments are processed by SWIG. For example: 102 103<blockquote> 104<pre> 105%include "typemaps.i" 106void add(int *INPUT, int *INPUT, int *OUTPUT); 107</pre> 108</blockquote> 109 110And in a script: 111 112<blockquote> 113<pre> 114r = add(37,42) 115print "Result =",r 116</pre> 117</blockquote> 118Needless to say, this is substantially easier. 119 120<p> 121<li>A final alternative is to use the typemaps library in combination 122with the %apply directive. This allows you to change the names of parameters 123that behave as input or output parameters. For example: 124 125<blockquote> 126<pre> 127%include "typemaps.i" 128%apply int *INPUT {int *x, int *y}; 129%apply int *OUTPUT {int *r}; 130 131void add(int *x, int *y, int *r); 132void sub(int *x, int *y, int *r); 133void mul(int *x, int *y, int *r); 134... etc ... 135</pre> 136</blockquote> 137 138</ul> 139 140<h2>Example</h2> 141 142The following example illustrates the use of these features for pointer 143extraction. 144 145<ul> 146<li> <a href="example.c">example.c</a> (C Source) 147<li> <a href="example.i">example.i</a> (SWIG interface) 148<li> <a href="example.py">example.py</a> (Python Script) 149</ul> 150 151<h2>Notes</h2> 152 153<ul> 154<li>Since pointers are used for so many different things (arrays, output values, 155etc...) the complexity of pointer handling can be as complicated as you want to 156make it. 157 158<p> 159<li>More documentation on the typemaps.i and pointer.i library files can be 160found in the SWIG user manual. The files also contain documentation. 161 162<p> 163<li>The pointer.i library is designed primarily for convenience. If you 164are concerned about performance, you probably want to use a different 165approach. 166 167</ul> 168 169<hr> 170</body> 171</html>