/tags/rel-1-3-25/SWIG/Lib/python/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
 16// ------------------------------------------------------------------------
 17// Pointer handling
 18//
 19// These mappings provide support for input/output arguments and common
 20// uses for C/C++ pointers.
 21// ------------------------------------------------------------------------
 22
 23// INPUT typemaps.
 24// These remap a C pointer to be an "INPUT" value which is passed by value
 25// instead of reference.
 26
 27/* 
 28The following methods can be applied to turn a pointer into a simple
 29"input" value.  That is, instead of passing a pointer to an object,
 30you would use a real value instead.
 31
 32         int            *INPUT
 33         short          *INPUT
 34         long           *INPUT
 35	 long long      *INPUT
 36         unsigned int   *INPUT
 37         unsigned short *INPUT
 38         unsigned long  *INPUT
 39         unsigned long long *INPUT
 40         unsigned char  *INPUT
 41         bool           *INPUT
 42         float          *INPUT
 43         double         *INPUT
 44         
 45To use these, suppose you had a C function like this :
 46
 47        double fadd(double *a, double *b) {
 48               return *a+*b;
 49        }
 50
 51You could wrap it with SWIG as follows :
 52        
 53        %include <typemaps.i>
 54        double fadd(double *INPUT, double *INPUT);
 55
 56or you can use the %apply directive :
 57
 58        %include <typemaps.i>
 59        %apply double *INPUT { double *a, double *b };
 60        double fadd(double *a, double *b);
 61
 62*/
 63
 64// OUTPUT typemaps.   These typemaps are used for parameters that
 65// are output only.   The output value is appended to the result as
 66// a list element.
 67
 68/* 
 69The following methods can be applied to turn a pointer into an "output"
 70value.  When calling a function, no input value would be given for
 71a parameter, but an output value would be returned.  In the case of
 72multiple output values, they are returned in the form of a Python tuple.
 73
 74         int            *OUTPUT
 75         short          *OUTPUT
 76         long           *OUTPUT
 77         long long      *OUTPUT
 78         unsigned int   *OUTPUT
 79         unsigned short *OUTPUT
 80         unsigned long  *OUTPUT
 81         unsigned long long *OUTPUT
 82         unsigned char  *OUTPUT
 83         bool           *OUTPUT
 84         float          *OUTPUT
 85         double         *OUTPUT
 86         
 87For example, suppose you were trying to wrap the modf() function in the
 88C math library which splits x into integral and fractional parts (and
 89returns the integer part in one of its parameters).K:
 90
 91        double modf(double x, double *ip);
 92
 93You could wrap it with SWIG as follows :
 94
 95        %include <typemaps.i>
 96        double modf(double x, double *OUTPUT);
 97
 98or you can use the %apply directive :
 99
100        %include <typemaps.i>
101        %apply double *OUTPUT { double *ip };
102        double modf(double x, double *ip);
103
104The Python output of the function would be a tuple containing both
105output values. 
106
107*/
108
109// INOUT
110// Mappings for an argument that is both an input and output
111// parameter
112
113/*
114The following methods can be applied to make a function parameter both
115an input and output value.  This combines the behavior of both the
116"INPUT" and "OUTPUT" methods described earlier.  Output values are
117returned in the form of a Python tuple.  
118
119         int            *INOUT
120         short          *INOUT
121         long           *INOUT
122         long long      *INOUT
123         unsigned int   *INOUT
124         unsigned short *INOUT
125         unsigned long  *INOUT
126         unsigned long long *INOUT
127         unsigned char  *INOUT
128         bool           *INOUT
129         float          *INOUT
130         double         *INOUT
131         
132For example, suppose you were trying to wrap the following function :
133
134        void neg(double *x) {
135             *x = -(*x);
136        }
137
138You could wrap it with SWIG as follows :
139
140        %include <typemaps.i>
141        void neg(double *INOUT);
142
143or you can use the %apply directive :
144
145        %include <typemaps.i>
146        %apply double *INOUT { double *x };
147        void neg(double *x);
148
149Unlike C, this mapping does not directly modify the input value (since
150this makes no sense in Python).  Rather, the modified input value shows
151up as the return value of the function.  Thus, to apply this function
152to a Python variable you might do this :
153
154       x = neg(x)
155
156Note : previous versions of SWIG used the symbol 'BOTH' to mark
157input/output arguments.   This is still supported, but will be slowly
158phased out in future releases.
159
160*/
161
162
163%include <pyinout.swg>
164
165#ifdef SWIG_INOUT_NODEF
166/*
167  Apply the INPUT/OUTPUT typemaps to all the C types (int, double, ...) if
168  not already defined.
169*/
170%define %typemap_inout(Code,AsMeth, CheckMeth, FromMeth, AsFrag, CheckFrag, FromFrag, ...)
171  _PYVAL_INPUT_TYPEMAP(SWIG_arg(Code), SWIG_arg(AsMeth), SWIG_arg(CheckMeth),
172		       SWIG_arg(AsFrag), SWIG_arg(CheckFrag), SWIG_arg(__VA_ARGS__));
173  _PYVAL_OUTPUT_TYPEMAP(SWIG_arg(FromMeth), SWIG_arg(FromFrag), SWIG_arg(__VA_ARGS__));
174  _PYVAL_INOUT_TYPEMAP(SWIG_arg(__VA_ARGS__));
175%enddef
176
177%define %typemap_inoutn(Code,...)
178  %typemap_inout(SWIG_arg(Code),
179		 SWIG_arg(SWIG_As(__VA_ARGS__)), 
180		 SWIG_arg(SWIG_Check(__VA_ARGS__)), 
181		 SWIG_arg(SWIG_From(__VA_ARGS__)), 
182		 SWIG_arg(SWIG_As_frag(__VA_ARGS__)), 
183		 SWIG_arg(SWIG_Check_frag(__VA_ARGS__)), 
184		 SWIG_arg(SWIG_From_frag(__VA_ARGS__)), 
185		 SWIG_arg(__VA_ARGS__));
186%enddef
187
188%apply_checkctypes(%typemap_inoutn)
189
190#endif