wxPython/SWIG/typemaps.i

   1 //
   2 // SWIG Typemap library
   3 // Dave Beazley
   4 // May 5, 1997
   5 //
   6 // Python implementation
   7 //
   8 // This library provides standard typemaps for modifying SWIG's behavior.
   9 // With enough entries in this file, I hope that very few people actually
  10 // ever need to write a typemap.
  11 //
  12 // Disclaimer : Unless you really understand how typemaps work, this file
  13 // probably isn't going to make much sense.
  14 //
  15 #ifdef AUTODOC
  16 %section "Typemap Library (Python)",info,after,pre,nosort,skip=1,chop_left=3,chop_right=0,chop_top=0,chop_bottom=0
  17 %text %{
  18 %include typemaps.i
  19
  20 The SWIG typemap library provides a language independent mechanism for
  21 supporting output arguments, input values, and other C function
  22 calling mechanisms.  The primary use of the library is to provide a
  23 better interface to certain C function--especially those involving
  24 pointers.
  25 %}
  26
  27 #endif
  28
  29 // ------------------------------------------------------------------------
  30 // Pointer handling
  31 //
  32 // These mappings provide support for input/output arguments and common
  33 // uses for C/C++ pointers.
  34 // ------------------------------------------------------------------------
  35
  36 // INPUT typemaps.
  37 // These remap a C pointer to be an "INPUT" value which is passed by value
  38 // instead of reference.
  39
  40
  41 #ifdef AUTODOC
  42 %subsection "Input Methods"
  43
  44 %text %{
  45 The following methods can be applied to turn a pointer into a simple
  46 "input" value.  That is, instead of passing a pointer to an object,
  47 you would use a real value instead.
  48
  49          int            *INPUT
  50          short          *INPUT
  51          long           *INPUT
  52          unsigned int   *INPUT
  53          unsigned short *INPUT
  54          unsigned long  *INPUT
  55          unsigned char  *INPUT
  56          float          *INPUT
  57          double         *INPUT
  58
  59 To use these, suppose you had a C function like this :
  60
  61         double fadd(double *a, double *b) {
  62                return *a+*b;
  63         }
  64
  65 You could wrap it with SWIG as follows :
  66
  67         %include typemaps.i
  68         double fadd(double *INPUT, double *INPUT);
  69
  70 or you can use the %apply directive :
  71
  72         %include typemaps.i
  73         %apply double *INPUT { double *a, double *b };
  74         double fadd(double *a, double *b);
  75
  76 %}
  77 #endif
  78
  79 %typemap(python,in) double *INPUT(double temp)
  80 {
  81   temp = PyFloat_AsDouble($source);
  82   $target = &temp;
  83 }
  84
  85 %typemap(python,in) float  *INPUT(float temp)
  86 {
  87   temp = (float) PyFloat_AsDouble($source);
  88   $target = &temp;
  89 }
  90
  91 %typemap(python,in) int            *INPUT(int temp)
  92 {
  93   temp = (int) PyInt_AsLong($source);
  94   $target = &temp;
  95 }
  96
  97 %typemap(python,in) short          *INPUT(short temp)
  98 {
  99   temp = (short) PyInt_AsLong($source);
 100   $target = &temp;
 101 }
 102
 103 %typemap(python,in) long           *INPUT(long temp)
 104 {
 105   temp = (long) PyInt_AsLong($source);
 106   $target = &temp;
 107 }
 108 %typemap(python,in) unsigned int   *INPUT(unsigned int temp)
 109 {
 110   temp = (unsigned int) PyInt_AsLong($source);
 111   $target = &temp;
 112 }
 113 %typemap(python,in) unsigned short *INPUT(unsigned short temp)
 114 {
 115   temp = (unsigned short) PyInt_AsLong($source);
 116   $target = &temp;
 117 }
 118 %typemap(python,in) unsigned long  *INPUT(unsigned long temp)
 119 {
 120   temp = (unsigned long) PyInt_AsLong($source);
 121   $target = &temp;
 122 }
 123 %typemap(python,in) unsigned char  *INPUT(unsigned char temp)
 124 {
 125   temp = (unsigned char) PyInt_AsLong($source);
 126   $target = &temp;
 127 }
 128
 129 %typemap(python,in) signed char  *INPUT(signed char temp)
 130 {
 131   temp = (unsigned char) PyInt_AsLong($source);
 132   $target = &temp;
 133 }
 134
 135 // OUTPUT typemaps.   These typemaps are used for parameters that
 136 // are output only.   The output value is appended to the result as
 137 // a list element.
 138
 139 #ifdef AUTODOC
 140 %subsection "Output Methods"
 141
 142 %text %{
 143 The following methods can be applied to turn a pointer into an "output"
 144 value.  When calling a function, no input value would be given for
 145 a parameter, but an output value would be returned.  In the case of
 146 multiple output values, they are returned in the form of a Python tuple.
 147
 148          int            *OUTPUT
 149          short          *OUTPUT
 150          long           *OUTPUT
 151          unsigned int   *OUTPUT
 152          unsigned short *OUTPUT
 153          unsigned long  *OUTPUT
 154          unsigned char  *OUTPUT
 155          float          *OUTPUT
 156          double         *OUTPUT
 157
 158 A Python List can also be returned by using L_OUTPUT instead of OUTPUT.
 159
 160 For example, suppose you were trying to wrap the modf() function in the
 161 C math library which splits x into integral and fractional parts (and
 162 returns the integer part in one of its parameters).K:
 163
 164         double modf(double x, double *ip);
 165
 166 You could wrap it with SWIG as follows :
 167
 168         %include typemaps.i
 169         double modf(double x, double *OUTPUT);
 170
 171 or you can use the %apply directive :
 172
 173         %include typemaps.i
 174         %apply double *OUTPUT { double *ip };
 175         double modf(double x, double *ip);
 176
 177 The Python output of the function would be a tuple containing both
 178 output values.
 179 %}
 180 #endif
 181
 182
 183 // I don't use this anywhere, get rid of it...
 184
 185 // Helper function for List output
 186 //  static PyObject* l_output_helper(PyObject* target, PyObject* o) {
 187 //      PyObject*   o2;
 188 //      if (!target) {
 189 //          target = o;
 190 //      } else if (target == Py_None) {
 191 //          Py_DECREF(Py_None);
 192 //          target = o;
 193 //      } else {
 194 //          if (!PyList_Check(target)) {
 195 //              o2 = target;
 196 //              target = PyList_New(0);
 197 //              PyList_Append(target, o2);
 198 //          Py_XDECREF(o2);
 199 //          }
 200 //          PyList_Append(target,o);
 201 //      Py_XDECREF(o);
 202 //      }
 203 //      return target;
 204 //  }
 205
 206 %{
 207 %}
 208
 209 // Force the argument to be ignored.
 210
 211 %typemap(python,ignore) int            *L_OUTPUT(int temp),
 212                         short          *L_OUTPUT(short temp),
 213                         long           *L_OUTPUT(long temp),
 214                         unsigned int   *L_OUTPUT(unsigned int temp),
 215                         unsigned short *L_OUTPUT(unsigned short temp),
 216                         unsigned long  *L_OUTPUT(unsigned long temp),
 217                         unsigned char  *L_OUTPUT(unsigned char temp),
 218                         signed char    *L_OUTPUT(signed char temp),
 219                         float          *L_OUTPUT(float temp),
 220                         double         *L_OUTPUT(double temp)
 221 {
 222   $target = &temp;
 223 }
 224
 225 %typemap(python,argout) int            *L_OUTPUT,
 226                         short          *L_OUTPUT,
 227                         long           *L_OUTPUT,
 228                         unsigned int   *L_OUTPUT,
 229                         unsigned short *L_OUTPUT,
 230                         unsigned long  *L_OUTPUT,
 231                         unsigned char  *L_OUTPUT,
 232                         signed char    *L_OUTPUT
 233 {
 234     PyObject *o;
 235     o = PyInt_FromLong((long) (*$source));
 236     l_output_helper($target,o);
 237 }
 238
 239 %typemap(python,argout) float    *L_OUTPUT,
 240                         double   *L_OUTPUT
 241 {
 242     PyObject *o;
 243     o = PyFloat_FromDouble((double) (*$source));
 244     $target = l_output_helper($target,o);
 245 }
 246
 247 // These typemaps contributed by Robin Dunn
 248 //----------------------------------------------------------------------
 249 //
 250 // T_OUTPUT typemap (and helper function) to return multiple argouts as
 251 // a tuple instead of a list.
 252 //
 253 // Author: Robin Dunn
 254 //----------------------------------------------------------------------
 255
 256 %{
 257 static PyObject* t_output_helper(PyObject* target, PyObject* o) {
 258     PyObject*   o2;
 259     PyObject*   o3;
 260
 261     if (!target) {
 262         target = o;
 263     } else if (target == Py_None) {
 264         Py_DECREF(Py_None);
 265         target = o;
 266     } else {
 267         if (!PyTuple_Check(target)) {
 268             o2 = target;
 269             target = PyTuple_New(1);
 270             PyTuple_SetItem(target, 0, o2);
 271         }
 272         o3 = PyTuple_New(1);
 273         PyTuple_SetItem(o3, 0, o);
 274
 275         o2 = target;
 276         target = PySequence_Concat(o2, o3);
 277         Py_DECREF(o2);
 278         Py_DECREF(o3);
 279     }
 280     return target;
 281 }
 282 %}
 283
 284 // Force the argument to be ignored.
 285 %typemap(python,ignore) int            *T_OUTPUT(int temp),
 286                         short          *T_OUTPUT(short temp),
 287                         long           *T_OUTPUT(long temp),
 288                         unsigned int   *T_OUTPUT(unsigned int temp),
 289                         unsigned short *T_OUTPUT(unsigned short temp),
 290                         unsigned long  *T_OUTPUT(unsigned long temp),
 291                         unsigned char  *T_OUTPUT(unsigned char temp),
 292                         float          *T_OUTPUT(float temp),
 293                         double         *T_OUTPUT(double temp)
 294 {
 295   $target = &temp;
 296 }
 297
 298 %typemap(python,argout) int            *T_OUTPUT,
 299                         short          *T_OUTPUT,
 300                         long           *T_OUTPUT,
 301                         unsigned int   *T_OUTPUT,
 302                         unsigned short *T_OUTPUT,
 303                         unsigned long  *T_OUTPUT,
 304                         unsigned char  *T_OUTPUT
 305 {
 306     PyObject *o;
 307     o = PyInt_FromLong((long) (*$source));
 308     $target = t_output_helper($target, o);
 309 }
 310
 311 %typemap(python,argout) float    *T_OUTPUT,
 312                         double   *T_OUTPUT
 313 {
 314     PyObject *o;
 315     o = PyFloat_FromDouble((double) (*$source));
 316     $target = t_output_helper($target, o);
 317 }
 318
 319 // Set the default output typemap
 320
 321 #ifdef OUTPUT_LIST
 322 %typemap(python,ignore) int                *OUTPUT = int   *L_OUTPUT;
 323 %typemap(python,ignore) short              *OUTPUT = short *L_OUTPUT;
 324 %typemap(python,ignore) long               *OUTPUT = long  *L_OUTPUT;
 325 %typemap(python,ignore) unsigned           *OUTPUT = unsigned *L_OUTPUT;
 326 %typemap(python,ignore) unsigned short     *OUTPUT = unsigned short *L_OUTPUT;
 327 %typemap(python,ignore) unsigned long      *OUTPUT = unsigned long  *L_OUTPUT;
 328 %typemap(python,ignore) unsigned char      *OUTPUT = unsigned char  *L_OUTPUT;
 329 %typemap(python,ignore) signed char        *OUTPUT = signed char    *L_OUTPUT;
 330 %typemap(python,ignore) double             *OUTPUT = double         *L_OUTPUT;
 331 %typemap(python,ignore) float              *OUTPUT = float          *L_OUTPUT;
 332
 333 %typemap(python,argout) int                *OUTPUT = int   *L_OUTPUT;
 334 %typemap(python,argout) short              *OUTPUT = short *L_OUTPUT;
 335 %typemap(python,argout) long               *OUTPUT = long  *L_OUTPUT;
 336 %typemap(python,argout) unsigned           *OUTPUT = unsigned *L_OUTPUT;
 337 %typemap(python,argout) unsigned short     *OUTPUT = unsigned short *L_OUTPUT;
 338 %typemap(python,argout) unsigned long      *OUTPUT = unsigned long  *L_OUTPUT;
 339 %typemap(python,argout) unsigned char      *OUTPUT = unsigned char  *L_OUTPUT;
 340 %typemap(python,argout) signed char        *OUTPUT = signed char    *L_OUTPUT;
 341 %typemap(python,argout) double             *OUTPUT = double         *L_OUTPUT;
 342 %typemap(python,argout) float              *OUTPUT = float          *L_OUTPUT;
 343 #else
 344 %typemap(python,ignore) int                *OUTPUT = int   *T_OUTPUT;
 345 %typemap(python,ignore) short              *OUTPUT = short *T_OUTPUT;
 346 %typemap(python,ignore) long               *OUTPUT = long  *T_OUTPUT;
 347 %typemap(python,ignore) unsigned           *OUTPUT = unsigned *T_OUTPUT;
 348 %typemap(python,ignore) unsigned short     *OUTPUT = unsigned short *T_OUTPUT;
 349 %typemap(python,ignore) unsigned long      *OUTPUT = unsigned long  *T_OUTPUT;
 350 %typemap(python,ignore) unsigned char      *OUTPUT = unsigned char  *T_OUTPUT;
 351 %typemap(python,ignore) signed char        *OUTPUT = signed char    *T_OUTPUT;
 352 %typemap(python,ignore) double             *OUTPUT = double         *T_OUTPUT;
 353 %typemap(python,ignore) float              *OUTPUT = float          *T_OUTPUT;
 354
 355 %typemap(python,argout) int                *OUTPUT = int   *T_OUTPUT;
 356 %typemap(python,argout) short              *OUTPUT = short *T_OUTPUT;
 357 %typemap(python,argout) long               *OUTPUT = long  *T_OUTPUT;
 358 %typemap(python,argout) unsigned           *OUTPUT = unsigned *T_OUTPUT;
 359 %typemap(python,argout) unsigned short     *OUTPUT = unsigned short *T_OUTPUT;
 360 %typemap(python,argout) unsigned long      *OUTPUT = unsigned long  *T_OUTPUT;
 361 %typemap(python,argout) unsigned char      *OUTPUT = unsigned char  *T_OUTPUT;
 362 %typemap(python,argout) signed char        *OUTPUT = signed char    *T_OUTPUT;
 363 %typemap(python,argout) double             *OUTPUT = double         *T_OUTPUT;
 364 %typemap(python,argout) float              *OUTPUT = float          *T_OUTPUT;
 365 #endif
 366
 367 // INOUT
 368 // Mappings for an argument that is both an input and output
 369 // parameter
 370
 371
 372 #ifdef AUTODOC
 373 %subsection "Input/Output Methods"
 374
 375 %text %{
 376 The following methods can be applied to make a function parameter both
 377 an input and output value.  This combines the behavior of both the
 378 "INPUT" and "OUTPUT" methods described earlier.  Output values are
 379 returned in the form of a Python tuple.  To return a Python list,
 380 using L_INOUT instead.
 381
 382          int            *INOUT
 383          short          *INOUT
 384          long           *INOUT
 385          unsigned int   *INOUT
 386          unsigned short *INOUT
 387          unsigned long  *INOUT
 388          unsigned char  *INOUT
 389          float          *INOUT
 390          double         *INOUT
 391
 392 For example, suppose you were trying to wrap the following function :
 393
 394         void neg(double *x) {
 395              *x = -(*x);
 396         }
 397
 398 You could wrap it with SWIG as follows :
 399
 400         %include typemaps.i
 401         void neg(double *INOUT);
 402
 403 or you can use the %apply directive :
 404
 405         %include typemaps.i
 406         %apply double *INOUT { double *x };
 407         void neg(double *x);
 408
 409 Unlike C, this mapping does not directly modify the input value (since
 410 this makes no sense in Python).  Rather, the modified input value shows
 411 up as the return value of the function.  Thus, to apply this function
 412 to a Python variable you might do this :
 413
 414        x = neg(x)
 415
 416 Note : previous versions of SWIG used the symbol 'BOTH' to mark
 417 input/output arguments.   This is still supported, but will be slowly
 418 phased out in future releases.
 419 %}
 420
 421 #endif
 422
 423 %typemap(python,in) int *INOUT = int *INPUT;
 424 %typemap(python,in) short *INOUT = short *INPUT;
 425 %typemap(python,in) long *INOUT = long *INPUT;
 426 %typemap(python,in) unsigned *INOUT = unsigned *INPUT;
 427 %typemap(python,in) unsigned short *INOUT = unsigned short *INPUT;
 428 %typemap(python,in) unsigned long *INOUT = unsigned long *INPUT;
 429 %typemap(python,in) unsigned char *INOUT = unsigned char *INPUT;
 430 %typemap(python,in) float *INOUT = float *INPUT;
 431 %typemap(python,in) double *INOUT = double *INPUT;
 432
 433 %typemap(python,argout) int *INOUT = int *OUTPUT;
 434 %typemap(python,argout) short *INOUT = short *OUTPUT;
 435 %typemap(python,argout) long *INOUT = long *OUTPUT;
 436 %typemap(python,argout) unsigned *INOUT = unsigned *OUTPUT;
 437 %typemap(python,argout) unsigned short *INOUT = unsigned short *OUTPUT;
 438 %typemap(python,argout) unsigned long *INOUT = unsigned long *OUTPUT;
 439 %typemap(python,argout) unsigned char *INOUT = unsigned char *OUTPUT;
 440 %typemap(python,argout) float *INOUT = float *OUTPUT;
 441 %typemap(python,argout) double *INOUT = double *OUTPUT;
 442
 443 %typemap(python,in) int *T_INOUT = int *INPUT;
 444 %typemap(python,in) short *T_INOUT = short *INPUT;
 445 %typemap(python,in) long *T_INOUT = long *INPUT;
 446 %typemap(python,in) unsigned *T_INOUT = unsigned *INPUT;
 447 %typemap(python,in) unsigned short *T_INOUT = unsigned short *INPUT;
 448 %typemap(python,in) unsigned long *T_INOUT = unsigned long *INPUT;
 449 %typemap(python,in) unsigned char *T_INOUT = unsigned char *INPUT;
 450 %typemap(python,in) float *T_INOUT = float *INPUT;
 451 %typemap(python,in) double *T_INOUT = double *INPUT;
 452
 453 %typemap(python,argout) int *T_INOUT = int *T_OUTPUT;
 454 %typemap(python,argout) short *T_INOUT = short *T_OUTPUT;
 455 %typemap(python,argout) long *T_INOUT = long *T_OUTPUT;
 456 %typemap(python,argout) unsigned *T_INOUT = unsigned *T_OUTPUT;
 457 %typemap(python,argout) unsigned short *T_INOUT = unsigned short *T_OUTPUT;
 458 %typemap(python,argout) unsigned long *T_INOUT = unsigned long *T_OUTPUT;
 459 %typemap(python,argout) unsigned char *T_INOUT = unsigned char *T_OUTPUT;
 460 %typemap(python,argout) float *T_INOUT = float *T_OUTPUT;
 461 %typemap(python,argout) double *T_INOUT = double *T_OUTPUT;
 462
 463 %typemap(python,in) int *L_INOUT = int *INPUT;
 464 %typemap(python,in) short *L_INOUT = short *INPUT;
 465 %typemap(python,in) long *L_INOUT = long *INPUT;
 466 %typemap(python,in) unsigned *L_INOUT = unsigned *INPUT;
 467 %typemap(python,in) unsigned short *L_INOUT = unsigned short *INPUT;
 468 %typemap(python,in) unsigned long *L_INOUT = unsigned long *INPUT;
 469 %typemap(python,in) unsigned char *L_INOUT = unsigned char *INPUT;
 470 %typemap(python,in) float *L_INOUT = float *INPUT;
 471 %typemap(python,in) double *L_INOUT = double *INPUT;
 472
 473 %typemap(python,argout) int *L_INOUT = int *L_OUTPUT;
 474 %typemap(python,argout) short *L_INOUT = short *L_OUTPUT;
 475 %typemap(python,argout) long *L_INOUT = long *L_OUTPUT;
 476 %typemap(python,argout) unsigned *L_INOUT = unsigned *L_OUTPUT;
 477 %typemap(python,argout) unsigned short *L_INOUT = unsigned short *L_OUTPUT;
 478 %typemap(python,argout) unsigned long *L_INOUT = unsigned long *L_OUTPUT;
 479 %typemap(python,argout) unsigned char *L_INOUT = unsigned char *L_OUTPUT;
 480 %typemap(python,argout) float *L_INOUT = float *L_OUTPUT;
 481 %typemap(python,argout) double *L_INOUT = double *L_OUTPUT;
 482
 483 // Backwards compatibility
 484
 485 %typemap(python,in) int *BOTH = int *INOUT;
 486 %typemap(python,in) short *BOTH = short *INOUT;
 487 %typemap(python,in) long *BOTH = long *INOUT;
 488 %typemap(python,in) unsigned *BOTH = unsigned *INOUT;
 489 %typemap(python,in) unsigned short *BOTH = unsigned short *INOUT;
 490 %typemap(python,in) unsigned long *BOTH = unsigned long *INOUT;
 491 %typemap(python,in) unsigned char *BOTH = unsigned char *INOUT;
 492 %typemap(python,in) float *BOTH = float *INOUT;
 493 %typemap(python,in) double *BOTH = double *INOUT;
 494
 495 %typemap(python,argout) int *BOTH = int *INOUT;
 496 %typemap(python,argout) short *BOTH = short *INOUT;
 497 %typemap(python,argout) long *BOTH = long *INOUT;
 498 %typemap(python,argout) unsigned *BOTH = unsigned *INOUT;
 499 %typemap(python,argout) unsigned short *BOTH = unsigned short *INOUT;
 500 %typemap(python,argout) unsigned long *BOTH = unsigned long *INOUT;
 501 %typemap(python,argout) unsigned char *BOTH = unsigned char *INOUT;
 502 %typemap(python,argout) float *BOTH = float *INOUT;
 503 %typemap(python,argout) double *BOTH = double *INOUT;
 504
 505 %typemap(python,in) int *T_BOTH = int *T_INOUT;
 506 %typemap(python,in) short *T_BOTH = short *T_INOUT;
 507 %typemap(python,in) long *T_BOTH = long *T_INOUT;
 508 %typemap(python,in) unsigned *T_BOTH = unsigned *T_INOUT;
 509 %typemap(python,in) unsigned short *T_BOTH = unsigned short *T_INOUT;
 510 %typemap(python,in) unsigned long *T_BOTH = unsigned long *T_INOUT;
 511 %typemap(python,in) unsigned char *T_BOTH = unsigned char *T_INOUT;
 512 %typemap(python,in) float *T_BOTH = float *T_INOUT;
 513 %typemap(python,in) double *T_BOTH = double *T_INOUT;
 514
 515 %typemap(python,argout) int *T_BOTH = int *T_INOUT;
 516 %typemap(python,argout) short *T_BOTH = short *T_INOUT;
 517 %typemap(python,argout) long *T_BOTH = long *T_INOUT;
 518 %typemap(python,argout) unsigned *T_BOTH = unsigned *T_INOUT;
 519 %typemap(python,argout) unsigned short *T_BOTH = unsigned short *T_INOUT;
 520 %typemap(python,argout) unsigned long *T_BOTH = unsigned long *T_INOUT;
 521 %typemap(python,argout) unsigned char *T_BOTH = unsigned char *T_INOUT;
 522 %typemap(python,argout) float *T_BOTH = float *T_INOUT;
 523 %typemap(python,argout) double *T_BOTH = double *T_INOUT;
 524
 525 // --------------------------------------------------------------------
 526 // Special types
 527 //
 528 // --------------------------------------------------------------------
 529
 530 #ifdef AUTODOC
 531 %subsection "Special Methods"
 532
 533 %text %{
 534 The typemaps.i library also provides the following mappings :
 535
 536 PyObject *
 537
 538       When a PyObject * appears as either an input value or return
 539       value of a function, SWIG passes it through unmodified.  Thus,
 540       if you want to write a C function that operates on PyObjects,
 541       it is easy to write.  For example :
 542
 543            %include typemaps.i
 544            PyObject *spam(PyObject *obj1, int n);
 545
 546       Unlike normal Python wrapper functions, These functions can
 547       use any combination of parameters that you wish.
 548
 549 %}
 550
 551 #endif
 552
 553
 554 // If a PyObject * appears as either an argument or a function return
 555 // value, simply pass it straight through.
 556
 557 %typemap(python,in) PyObject * {
 558   $target = $source;
 559 }
 560
 561 %typemap(python,out) PyObject * {
 562   $target = $source;
 563 }
 564