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