1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Argument Handling</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Arguments">10 Argument Handling</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Arguments_nn2">The typemaps.i library</a>
<ul>
<li><a href="#Arguments_nn3">Introduction</a>
<li><a href="#Arguments_nn4">Input parameters</a>
<li><a href="#Arguments_nn5">Output parameters</a>
<li><a href="#Arguments_nn6">Input/Output parameters</a>
<li><a href="#Arguments_nn7">Using different names</a>
</ul>
<li><a href="#Arguments_nn8">Applying constraints to input values</a>
<ul>
<li><a href="#Arguments_nn9">Simple constraint example</a>
<li><a href="#Arguments_nn10">Constraint methods</a>
<li><a href="#Arguments_nn11">Applying constraints to new datatypes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
In Chapter 3, SWIG's treatment of basic datatypes and pointers was
described. In particular, primitive types such as <tt>int</tt> and
<tt>double</tt> are mapped to corresponding types in the target
language. For everything else, pointers are used to refer to
structures, classes, arrays, and other user-defined datatypes.
However, in certain applications it is desirable to change SWIG's
handling of a specific datatype. For example, you might want to
return multiple values through the arguments of a function. This chapter
describes some of the techniques for doing this.
</p>
<H2><a name="Arguments_nn2">10.1 The typemaps.i library</a></H2>
<p>
This section describes the <tt>typemaps.i</tt> library file--commonly used to
change certain properties of argument conversion.
</p>
<H3><a name="Arguments_nn3">10.1.1 Introduction</a></H3>
<p>
Suppose you had a C function like this:
</p>
<div class="code"><pre>
void add(double a, double b, double *result) {
*result = a + b;
}
</pre></div>
<p>
From reading the source code, it is clear that the function is storing
a value in the <tt>double *result</tt> parameter. However, since SWIG
does not examine function bodies, it has no way to know that this is
the underlying behavior.
</p>
<p>
One way to deal with this is to use the
<tt>typemaps.i</tt> library file and write interface code like this:
</p>
<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"
%apply double *OUTPUT { double *result };
%inline %{
extern void add(double a, double b, double *result);
%}
</pre></div>
<p>
The <tt>%apply</tt> directive tells SWIG that you are going to apply
a special type handling rule to a type. The "<tt>double *OUTPUT</tt>" specification is the
name of a rule that defines how to return an output value from an argument of type
<tt>double *</tt>. This rule gets applied to all of the datatypes
listed in curly braces-- in this case "<tt>double *result</tt>".</p>
<p>
When the resulting module is created, you can now use the function
like this (shown for Python):
</p>
<div class="targetlang"><pre>
>>> a = add(3,4)
>>> print a
7
>>>
</pre></div>
<p>
In this case, you can see how the output value normally returned in
the third argument has magically been transformed into a function
return value. Clearly this makes the function much easier to use
since it is no longer necessary to manufacture a special <tt>double
*</tt> object and pass it to the function somehow.
</p>
<p>
Once a typemap has been applied to a type, it stays in effect for all future occurrences
of the type and name. For example, you could write the following:
</p>
<div class="code"><pre>
%module example
%include "typemaps.i"
%apply double *OUTPUT { double *result };
%inline %{
extern void add(double a, double b, double *result);
extern void sub(double a, double b, double *result);
extern void mul(double a, double b, double *result);
extern void div(double a, double b, double *result);
%}
...
</pre></div>
<p>
In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the functions that follow.
</p>
<p>
Typemap transformations can even be extended to multiple return values.
For example, consider this code:
</p>
<div class="code">
<pre>
%include "typemaps.i"
%apply int *OUTPUT { int *width, int *height };
// Returns a pair (width,height)
void getwinsize(int winid, int *width, int *height);
</pre>
</div>
<p>
In this case, the function returns multiple values, allowing it to be used like this:
</p>
<div class="targetlang"><pre>
>>> w,h = genwinsize(wid)
>>> print w
400
>>> print h
300
>>>
</pre>
</div>
<p>
It should also be noted that although the <tt>%apply</tt> directive is
used to associate typemap rules to datatypes, you can also use the
rule names directly in arguments. For example, you could write this:
</p>
<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"
%{
extern void add(double a, double b, double *OUTPUT);
%}
extern void add(double a, double b, double *OUTPUT);
</pre></div>
<p>
Typemaps stay in effect until they are explicitly deleted or redefined to something
else. To clear a typemap, the <tt>%clear</tt> directive should be used. For example:
</p>
<div class="code">
<pre>
%clear double *result; // Remove all typemaps for double *result
</pre>
</div>
<H3><a name="Arguments_nn4">10.1.2 Input parameters</a></H3>
<p>
The following typemaps instruct SWIG that a pointer really only holds a single
input value:
</p>
<div class="code"><pre>
int *INPUT
short *INPUT
long *INPUT
unsigned int *INPUT
unsigned short *INPUT
unsigned long *INPUT
double *INPUT
float *INPUT
</pre></div>
<p>
When used, it allows values to be passed instead of pointers. For example, consider this
function:
</p>
<div class="code"><pre>
double add(double *a, double *b) {
return *a+*b;
}
</pre></div>
<p>
Now, consider this SWIG interface:
</p>
<div class="code"><pre>
%module example
%include "typemaps.i"
...
%{
extern double add(double *, double *);
%}
extern double add(double *INPUT, double *INPUT);
</pre></div>
<p>
When the function is used in the scripting language interpreter, it will work like this:
</p>
<div class="targetlang"><pre>
result = add(3,4)
</pre></div>
<H3><a name="Arguments_nn5">10.1.3 Output parameters</a></H3>
<p>
The following typemap rules tell SWIG that pointer is the output value of a
function. When used, you do not need to supply the argument when
calling the function. Instead, one or more output values are returned.
</p>
<div class="code"><pre>
int *OUTPUT
short *OUTPUT
long *OUTPUT
unsigned int *OUTPUT
unsigned short *OUTPUT
unsigned long *OUTPUT
double *OUTPUT
float *OUTPUT
</pre></div>
<p>
These methods can be used as shown in an earlier example. For example, if you have this C function :</p>
<div class="code"><pre>
void add(double a, double b, double *c) {
*c = a+b;
}
</pre></div>
<p>
A SWIG interface file might look like this :</p>
<div class="code"><pre>
%module example
%include "typemaps.i"
...
%inline %{
extern void add(double a, double b, double *OUTPUT);
%}
</pre></div>
<p>
In this case, only a single output value is returned, but this is not
a restriction. An arbitrary number of output values can be returned by applying
the output rules to more than one argument (as shown previously).
</p>
<p>
If the function also returns a value, it is returned along with the argument. For example,
if you had this:
</p>
<div class="code"><pre>
extern int foo(double a, double b, double *OUTPUT);
</pre></div>
<p>
The function will return two values like this:
</p>
<div class="targetlang">
<pre>
iresult, dresult = foo(3.5, 2)
</pre>
</div>
<H3><a name="Arguments_nn6">10.1.4 Input/Output parameters</a></H3>
<p>
When a pointer serves as both an input and output value you can use
the following typemaps :</p>
<div class="code"><pre>
int *INOUT
short *INOUT
long *INOUT
unsigned int *INOUT
unsigned short *INOUT
unsigned long *INOUT
double *INOUT
float *INOUT
</pre></div>
<p>
A C function that uses this might be something like this:</p>
<div class="code"><pre>
void negate(double *x) {
*x = -(*x);
}
</pre></div>
<p>
To make x function as both and input and output value, declare the
function like this in an interface file :</p>
<div class="code"><pre>
%module example
%include "typemaps.i"
...
%{
extern void negate(double *);
%}
extern void negate(double *INOUT);
</pre></div>
<p>
Now within a script, you can simply call the function normally :</p>
<div class="targetlang"><pre>
a = negate(3); # a = -3 after calling this
</pre></div>
<p>
One subtle point of the <tt>INOUT</tt> rule is that many scripting languages
enforce mutability constraints on primitive objects (meaning that simple objects
like integers and strings aren't supposed to change). Because of this, you can't
just modify the object's value in place as the underlying C function does in this example.
Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
rather than directly overwriting the value of the original input object.
</p>
<p>
<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
SWIG. Backwards compatibility is preserved, but deprecated.
</p>
<H3><a name="Arguments_nn7">10.1.5 Using different names</a></H3>
<p>
As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>INPUT</tt>, <tt>OUTPUT</tt>, and
<tt>INOUT</tt> typemaps to different argument names. For example:
</p>
<div class="code"><pre>
// Make double *result an output value
%apply double *OUTPUT { double *result };
// Make Int32 *in an input value
%apply int *INPUT { Int32 *in };
// Make long *x inout
%apply long *INOUT {long *x};
</pre></div>
<p>
To clear a rule, the <tt>%clear</tt> directive is used:
</p>
<div class="code"><pre>
%clear double *result;
%clear Int32 *in, long *x;
</pre></div>
<p>
Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the
file or a matching <tt>%clear</tt> declaration.
</p>
<H2><a name="Arguments_nn8">10.2 Applying constraints to input values</a></H2>
<p>
In addition to changing the handling of various input values, it is
also possible to use typemaps to apply constraints. For example, maybe you want to
insure that a value is positive, or that a pointer is non-NULL. This
can be accomplished including the <tt>constraints.i</tt> library file.
</p>
<H3><a name="Arguments_nn9">10.2.1 Simple constraint example</a></H3>
<p>
The constraints library is best illustrated by the following interface
file :</p>
<div class="code"><pre>
// Interface file with constraints
%module example
%include "constraints.i"
double exp(double x);
double log(double POSITIVE); // Allow only positive values
double sqrt(double NONNEGATIVE); // Non-negative values only
double inv(double NONZERO); // Non-zero values
void free(void *NONNULL); // Non-NULL pointers only
</pre></div>
<p>
The behavior of this file is exactly as you would expect. If any of
the arguments violate the constraint condition, a scripting language
exception will be raised. As a result, it is possible to catch bad
values, prevent mysterious program crashes and so on.</p>
<H3><a name="Arguments_nn10">10.2.2 Constraint methods</a></H3>
<p>
The following constraints are currently available</p>
<div class="code"><pre>
POSITIVE Any number > 0 (not zero)
NEGATIVE Any number < 0 (not zero)
NONNEGATIVE Any number >= 0
NONPOSITIVE Any number <= 0
NONZERO Nonzero number
NONNULL Non-NULL pointer (pointers only).
</pre></div>
<H3><a name="Arguments_nn11">10.2.3 Applying constraints to new datatypes</a></H3>
<p>
The constraints library only supports the primitive C datatypes, but it
is easy to apply it to new datatypes using <tt>%apply</tt>. For
example :</p>
<div class="code"><pre>
// Apply a constraint to a Real variable
%apply Number POSITIVE { Real in };
// Apply a constraint to a pointer type
%apply Pointer NONNULL { Vector * };
</pre></div>
<p>
The special types of "Number" and "Pointer" can be applied to any
numeric and pointer variable type respectively. To later remove a
constraint, the <tt>%clear</tt> directive can be used :</p>
<div class="code"><pre>
%clear Real in;
%clear Vector *;
</pre></div>
</body>
</html>
|
