PageRenderTime 4ms CodeModel.GetById 1ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/Lib/python/typemaps.i

#
Swig | 148 lines | 10 code | 7 blank | 131 comment | 0 complexity | ca33baa4a719ab2395bf8ce4a46c9539 MD5 | raw file
  1/* -----------------------------------------------------------------------------
  2 * typemaps.i
  3 *
  4 * Pointer handling
  5 * These mappings provide support for input/output arguments and common
  6 * uses for C/C++ pointers.
  7 * ----------------------------------------------------------------------------- */
  8
  9// INPUT typemaps.
 10// These remap a C pointer to be an "INPUT" value which is passed by value
 11// instead of reference.
 12
 13/* 
 14The following methods can be applied to turn a pointer into a simple
 15"input" value.  That is, instead of passing a pointer to an object,
 16you would use a real value instead.
 17
 18         int            *INPUT
 19         short          *INPUT
 20         long           *INPUT
 21	 long long      *INPUT
 22         unsigned int   *INPUT
 23         unsigned short *INPUT
 24         unsigned long  *INPUT
 25         unsigned long long *INPUT
 26         unsigned char  *INPUT
 27         bool           *INPUT
 28         float          *INPUT
 29         double         *INPUT
 30         
 31To use these, suppose you had a C function like this :
 32
 33        double fadd(double *a, double *b) {
 34               return *a+*b;
 35        }
 36
 37You could wrap it with SWIG as follows :
 38        
 39        %include <typemaps.i>
 40        double fadd(double *INPUT, double *INPUT);
 41
 42or you can use the %apply directive :
 43
 44        %include <typemaps.i>
 45        %apply double *INPUT { double *a, double *b };
 46        double fadd(double *a, double *b);
 47
 48*/
 49
 50// OUTPUT typemaps.   These typemaps are used for parameters that
 51// are output only.   The output value is appended to the result as
 52// a list element.
 53
 54/* 
 55The following methods can be applied to turn a pointer into an "output"
 56value.  When calling a function, no input value would be given for
 57a parameter, but an output value would be returned.  In the case of
 58multiple output values, they are returned in the form of a Python tuple.
 59
 60         int            *OUTPUT
 61         short          *OUTPUT
 62         long           *OUTPUT
 63         long long      *OUTPUT
 64         unsigned int   *OUTPUT
 65         unsigned short *OUTPUT
 66         unsigned long  *OUTPUT
 67         unsigned long long *OUTPUT
 68         unsigned char  *OUTPUT
 69         bool           *OUTPUT
 70         float          *OUTPUT
 71         double         *OUTPUT
 72         
 73For example, suppose you were trying to wrap the modf() function in the
 74C math library which splits x into integral and fractional parts (and
 75returns the integer part in one of its parameters).K:
 76
 77        double modf(double x, double *ip);
 78
 79You could wrap it with SWIG as follows :
 80
 81        %include <typemaps.i>
 82        double modf(double x, double *OUTPUT);
 83
 84or you can use the %apply directive :
 85
 86        %include <typemaps.i>
 87        %apply double *OUTPUT { double *ip };
 88        double modf(double x, double *ip);
 89
 90The Python output of the function would be a tuple containing both
 91output values. 
 92
 93*/
 94
 95// INOUT
 96// Mappings for an argument that is both an input and output
 97// parameter
 98
 99/*
100The following methods can be applied to make a function parameter both
101an input and output value.  This combines the behavior of both the
102"INPUT" and "OUTPUT" methods described earlier.  Output values are
103returned in the form of a Python tuple.  
104
105         int            *INOUT
106         short          *INOUT
107         long           *INOUT
108         long long      *INOUT
109         unsigned int   *INOUT
110         unsigned short *INOUT
111         unsigned long  *INOUT
112         unsigned long long *INOUT
113         unsigned char  *INOUT
114         bool           *INOUT
115         float          *INOUT
116         double         *INOUT
117         
118For example, suppose you were trying to wrap the following function :
119
120        void neg(double *x) {
121             *x = -(*x);
122        }
123
124You could wrap it with SWIG as follows :
125
126        %include <typemaps.i>
127        void neg(double *INOUT);
128
129or you can use the %apply directive :
130
131        %include <typemaps.i>
132        %apply double *INOUT { double *x };
133        void neg(double *x);
134
135Unlike C, this mapping does not directly modify the input value (since
136this makes no sense in Python).  Rather, the modified input value shows
137up as the return value of the function.  Thus, to apply this function
138to a Python variable you might do this :
139
140       x = neg(x)
141
142Note : previous versions of SWIG used the symbol 'BOTH' to mark
143input/output arguments.   This is still supported, but will be slowly
144phased out in future releases.
145
146*/
147
148%include <typemaps/typemaps.swg>