Doc/Manual/Arguments.html

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