| 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 | /* |
| 28 | The 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, |
| 30 | you 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 | |
| 45 | To use these, suppose you had a C function like this : |
| 46 | |
| 47 | double fadd(double *a, double *b) { |
| 48 | return *a+*b; |
| 49 | } |
| 50 | |
| 51 | You could wrap it with SWIG as follows : |
| 52 | |
| 53 | %include <typemaps.i> |
| 54 | double fadd(double *INPUT, double *INPUT); |
| 55 | |
| 56 | or 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 | /* |
| 69 | The following methods can be applied to turn a pointer into an "output" |
| 70 | value. When calling a function, no input value would be given for |
| 71 | a parameter, but an output value would be returned. In the case of |
| 72 | multiple 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 | |
| 87 | For example, suppose you were trying to wrap the modf() function in the |
| 88 | C math library which splits x into integral and fractional parts (and |
| 89 | returns the integer part in one of its parameters).K: |
| 90 | |
| 91 | double modf(double x, double *ip); |
| 92 | |
| 93 | You could wrap it with SWIG as follows : |
| 94 | |
| 95 | %include <typemaps.i> |
| 96 | double modf(double x, double *OUTPUT); |
| 97 | |
| 98 | or 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 | |
| 104 | The Python output of the function would be a tuple containing both |
| 105 | output values. |
| 106 | |
| 107 | */ |
| 108 | |
| 109 | // INOUT |
| 110 | // Mappings for an argument that is both an input and output |
| 111 | // parameter |
| 112 | |
| 113 | /* |
| 114 | The following methods can be applied to make a function parameter both |
| 115 | an input and output value. This combines the behavior of both the |
| 116 | "INPUT" and "OUTPUT" methods described earlier. Output values are |
| 117 | returned 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 | |
| 132 | For example, suppose you were trying to wrap the following function : |
| 133 | |
| 134 | void neg(double *x) { |
| 135 | *x = -(*x); |
| 136 | } |
| 137 | |
| 138 | You could wrap it with SWIG as follows : |
| 139 | |
| 140 | %include <typemaps.i> |
| 141 | void neg(double *INOUT); |
| 142 | |
| 143 | or you can use the %apply directive : |
| 144 | |
| 145 | %include <typemaps.i> |
| 146 | %apply double *INOUT { double *x }; |
| 147 | void neg(double *x); |
| 148 | |
| 149 | Unlike C, this mapping does not directly modify the input value (since |
| 150 | this makes no sense in Python). Rather, the modified input value shows |
| 151 | up as the return value of the function. Thus, to apply this function |
| 152 | to a Python variable you might do this : |
| 153 | |
| 154 | x = neg(x) |
| 155 | |
| 156 | Note : previous versions of SWIG used the symbol 'BOTH' to mark |
| 157 | input/output arguments. This is still supported, but will be slowly |
| 158 | phased 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, Type...) |
| 171 | _PYVAL_INPUT_TYPEMAP(SWIG_arg(Code), SWIG_arg(AsMeth), SWIG_arg(CheckMeth), |
| 172 | SWIG_arg(AsFrag), SWIG_arg(CheckFrag), SWIG_arg(Type)); |
| 173 | _PYVAL_OUTPUT_TYPEMAP(SWIG_arg(FromMeth), SWIG_arg(FromFrag), SWIG_arg(Type)); |
| 174 | _PYVAL_INOUT_TYPEMAP(SWIG_arg(Type)); |
| 175 | %enddef |
| 176 | |
| 177 | %define %typemap_inoutn(Code,Type...) |
| 178 | %typemap_inout(SWIG_arg(Code), |
| 179 | SWIG_arg(SWIG_As(Type)), |
| 180 | SWIG_arg(SWIG_Check(Type)), |
| 181 | SWIG_arg(SWIG_From(Type)), |
| 182 | SWIG_arg(SWIG_As_frag(Type)), |
| 183 | SWIG_arg(SWIG_Check_frag(Type)), |
| 184 | SWIG_arg(SWIG_From_frag(Type)), |
| 185 | SWIG_arg(Type)); |
| 186 | %enddef |
| 187 | |
| 188 | %apply_checkctypes(%typemap_inoutn) |
| 189 | |
| 190 | #endif |