← Back to branch summary

~ubuntu-branches/ubuntu/maverick/swig1.3/maverick

« back to all changes in this revision

Viewing changes to Examples/ruby/pointer/index.html

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Landschoff
  • Date: 2002-03-29 01:56:07 UTC
  • Revision ID: james.westby@ubuntu.com-20020329015607-c0wt03xu8oy9ioj7
Tags: upstream-1.3.11
Import upstream version 1.3.11

Show diffs side-by-side

added added

removed removed

Lines of Context:
Examples/ruby/pointer/index.html
 
1
<html>
 
2
<head>
 
3
<title>SWIG:Examples:ruby:pointer</title>
 
4
</head>
 
5
 
 
6
<body bgcolor="#ffffff">
 
7
 
 
8
<tt>SWIG/Examples/ruby/pointer/</tt>
 
9
<hr>
 
10
 
 
11
<H2>Simple Pointer Handling</H2>
 
12
 
 
13
<tt>$Header: /cvs/projects/SWIG/Examples/ruby/pointer/index.html,v 1.1 2000/09/18 13:21:26 fukusima Exp $</tt><br>
 
14
 
 
15
<p>
 
16
This example illustrates a couple of techniques for handling
 
17
simple pointers in SWIG.  The prototypical example is a C function
 
18
that operates on pointers such as this:
 
19
 
 
20
<blockquote>
 
21
<pre>
 
22
void add(int *x, int *y, int *r) { 
 
23
    *r = *x + *y;
 
24
}
 
25
</pre>
 
26
</blockquote>
 
27
 
 
28
By default, SWIG wraps this function exactly as specified and creates
 
29
an interface that expects pointer objects for arguments.  The only
 
30
problem 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
 
36
example:
 
37
 
 
38
<blockquote>
 
39
<pre>
 
40
int *new_int(int ivalue) {
 
41
  int *i = (int *) malloc(sizeof(ivalue));
 
42
  *i = ivalue;
 
43
  return i;
 
44
}
 
45
int get_int(int *i) {
 
46
  return *i;
 
47
}
 
48
 
 
49
void delete_int(int *i) {
 
50
  free(i);
 
51
}
 
52
</pre>
 
53
</blockquote>
 
54
 
 
55
Now, 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)
 
62
add(a,b,c)
 
63
r = get_int(c)
 
64
print "Result = #{r}\n"
 
65
delete_int(a)
 
66
delete_int(b)
 
67
delete_int(c)
 
68
</pre>
 
69
</blockquote>
 
70
 
 
71
<p>
 
72
<li>Use the SWIG pointer library.  For example, in the interface file 
 
73
you would do this:
 
74
 
 
75
<blockquote>
 
76
<pre>
 
77
%include "pointer.i"
 
78
</pre>
 
79
</blockquote>
 
80
 
 
81
and 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")
 
88
add(a,b,c)
 
89
r = ptrvalue(c)
 
90
print "Result = #{r}\n"
 
91
ptrfree(a)
 
92
ptrfree(b)
 
93
ptrfree(c)
 
94
</pre>
 
95
</blockquote>
 
96
 
 
97
The advantage to using the pointer library is that it unifies some of the helper
 
98
functions behind a common set of names.  For example, the same set of functions work
 
99
with int, double, float, and other fundamental types.
 
100
 
 
101
<p>
 
102
<li>Use the SWIG typemap library.  This library allows you to completely
 
103
change the way arguments are processed by SWIG.  For example:
 
104
 
 
105
<blockquote>
 
106
<pre>
 
107
%include "typemaps.i"
 
108
void add(int *INPUT, int *INPUT, int *OUTPUT);
 
109
</pre>
 
110
</blockquote>
 
111
 
 
112
And in a script:
 
113
 
 
114
<blockquote>
 
115
<pre>
 
116
r = add(37,42)
 
117
print "Result = #{r}\n"
 
118
</pre>
 
119
</blockquote>
 
120
Needless to say, this is substantially easier.
 
121
 
 
122
<p>
 
123
<li>A final alternative is to use the typemaps library in combination
 
124
with the %apply directive.  This allows you to change the names of parameters
 
125
that 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
 
 
133
void add(int *x, int *y, int *r);
 
134
void sub(int *x, int *y, int *r);
 
135
void mul(int *x, int *y, int *r);
 
136
... etc ...
 
137
</pre>
 
138
</blockquote>
 
139
 
 
140
</ul>
 
141
 
 
142
<h2>Example</h2>
 
143
 
 
144
The following example illustrates the use of these features for pointer
 
145
extraction.
 
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="runme.rb">runme.rb</a> (Ruby 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,
 
157
etc...) the complexity of pointer handling can be as complicated as you want to
 
158
make it.
 
159
 
 
160
<p>
 
161
<li>More documentation on the typemaps.i and pointer.i library files can be
 
162
found 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
 
166
are concerned about performance, you probably want to use a different
 
167
approach.
 
168
 
 
169
</ul>
 
170
 
 
171
<hr>
 
172
</body>
 
173
</html>