/trunk/Lib/typemaps/typemaps.swg

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