PageRenderTime 5ms CodeModel.GetById 1ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 1ms

/trunk/Examples/ruby/pointer/index.html

#
HTML | 171 lines | 137 code | 34 blank | 0 comment | 0 complexity | c2feb6b9913b9d5c42fe68bfb31e0395 MD5 | raw file
  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<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}\n"
 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}\n"
 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}\n"
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="runme.rb">runme.rb</a> (Ruby 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>