44
47
<H2><a name="Arguments_nn2"></a>9.1 The typemaps.i library</H2>
47
51
This section describes the <tt>typemaps.i</tt> library file--commonly used to
48
52
change certain properties of argument conversion.
50
55
<H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3>
53
59
Suppose you had a C function like this:
62
<div class="code"><pre>
56
63
void add(double a, double b, double *result) {
62
69
From reading the source code, it is clear that the function is storing
70
77
<tt>typemaps.i</tt> library file and write interface code like this:
80
<div class="code"><pre>
74
81
// Simple example using typemaps
76
83
%include "typemaps.i"
78
85
%apply double *OUTPUT { double *result };
79
87
extern void add(double a, double b, double *result);
83
92
The <tt>%apply</tt> directive tells SWIG that you are going to apply
91
100
like this (shown for Python):
103
<div class="targetlang"><pre>
95
104
>>> a = add(3,4)
96
105
>>> print a
101
111
In this case, you can see how the output value normally returned in
102
112
the third argument has magically been transformed into a function
103
113
return value. Clearly this makes the function much easier to use
104
114
since it is no longer necessary to manufacture a special <tt>double
105
115
*</tt> object and pass it to the function somehow.
108
119
Once a typemap has been applied to a type, it stays in effect for all future occurrences
109
120
of the type and name. For example, you could write the following:
123
<div class="code"><pre>
114
125
%include "typemaps.i"
116
127
%apply double *OUTPUT { double *result };
117
130
extern void add(double a, double b, double *result);
118
131
extern void sub(double a, double b, double *result);
119
132
extern void mul(double a, double b, double *result);
120
133
extern void div(double a, double b, double *result);
124
139
In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the functions that follow.
127
143
Typemap transformations can even be extended to multiple return values.
128
144
For example, consider this code:
133
149
%include "typemaps.i"
134
150
%apply int *OUTPUT { int *width, int *height };
136
152
// Returns a pair (width,height)
137
153
void getwinsize(int winid, int *width, int *height);
141
158
In this case, the function returns multiple values, allowing it to be used like this:
161
<div class="targetlang"><pre>
144
162
>>> w,h = genwinsize(wid)
145
163
>>> print w
156
174
rule names directly in arguments. For example, you could write this:
177
<div class="code"><pre>
160
178
// Simple example using typemaps
162
180
%include "typemaps.i"
164
extern void add(double a, double b, double *OUTPUT);
183
extern void add(double a, double b, double *OUTPUT);
185
extern void add(double a, double b, double *OUTPUT);
167
189
Typemaps stay in effect until they are explicitly deleted or redefined to something
168
190
else. To clear a typemap, the <tt>%clear</tt> directive should be used. For example:
172
195
%clear double *result; // Remove all typemaps for double *result
176
199
<H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3>
190
213
unsigned long *INPUT
195
219
When used, it allows values to be passed instead of pointers. For example, consider this
223
<div class="code"><pre>
199
224
double add(double *a, double *b) {
204
230
Now, consider this SWIG interface:
233
<div class="code"><pre>
208
235
%include "typemaps.i"
238
extern double add(double *, double *);
210
240
extern double add(double *INPUT, double *INPUT);
215
245
When the function is used in the scripting language interpreter, it will work like this:
248
<div class="targetlang"><pre>
219
249
result = add(3,4)
222
252
<H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3>
243
273
These methods can be used as shown in an earlier example. For example, if you have this C function :</p>
275
<div class="code"><pre>
246
276
void add(double a, double b, double *c) {
252
282
A SWIG interface file might look like this :</p>
284
<div class="code"><pre>
256
286
%include "typemaps.i"
258
289
extern void add(double a, double b, double *OUTPUT);
262
295
In this case, only a single output value is returned, but this is not
263
296
a restriction. An arbitrary number of output values can be returned by applying
264
297
the output rules to more than one argument (as shown previously).
267
301
If the function also returns a value, it is returned along with the argument. For example,
305
<div class="code"><pre>
272
306
extern int foo(double a, double b, double *OUTPUT);
275
310
The function will return two values like this:
313
<div class="targetlang">
279
315
iresult, dresult = foo(3.5, 2)
283
319
<H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3>
303
339
A C function that uses this might be something like this:</p>
341
<div class="code"><pre>
306
342
void negate(double *x) {
313
349
To make x function as both and input and output value, declare the
314
350
function like this in an interface file :</p>
352
<div class="code"><pre>
318
354
%include typemaps.i
357
extern void negate(double *);
320
359
extern void negate(double *INOUT);
325
364
Now within a script, you can simply call the function normally :</p>
366
<div class="targetlang"><pre>
328
367
a = negate(3); # a = -3 after calling this
331
371
One subtle point of the <tt>INOUT</tt> rule is that many scripting languages
332
372
enforce mutability constraints on primitive objects (meaning that simple objects
333
373
like integers and strings aren't supposed to change). Because of this, you can't
334
374
just modify the object's value in place as the underlying C function does in this example.
335
375
Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
336
376
rather than directly overwriting the value of the original input object.
339
380
<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
358
399
// Make long *x inout
359
400
%apply long *INOUT {long *x};
363
405
To clear a rule, the <tt>%clear</tt> directive is used:
408
<div class="code"><pre>
366
409
%clear double *result;
367
410
%clear Int32 *in, long *x;
370
414
Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the
371
415
file or a matching <tt>%clear</tt> declaration.
373
418
<H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2>
376
422
In addition to changing the handling of various input values, it is
377
423
also possible to use typemaps to apply constraints. For example, maybe you want to
378
424
insure that a value is positive, or that a pointer is non-NULL. This
379
425
can be accomplished including the <tt>constraints.i</tt> library file.
381
428
<H3><a name="Arguments_nn9"></a>9.2.1 Simple constraint example</H3>
428
475
is easy to apply it to new datatypes using <tt>%apply</tt>. For
478
<div class="code"><pre>
432
479
// Apply a constraint to a Real variable
433
480
%apply Number POSITIVE { Real in };
435
482
// Apply a constraint to a pointer type
436
483
%apply Pointer NONNULL { Vector * };
441
488
The special types of "Number" and "Pointer" can be applied to any
442
489
numeric and pointer variable type respectively. To later remove a
443
490
constraint, the <tt>%clear</tt> directive can be used :</p>
492
<div class="code"><pre>
added
removed
Doc/Manual/Arguments.html
