keep old typemap code in place, but disable, for readers to look around, and rescue other lost typemaps

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@7980 626c5289-ae23-0410-ae9c-e8d60b6d4f22

SWIG/Lib/python/typemaps.i

@@ -1 +1,162 @@
+//
+// SWIG Typemap library
+// Dave Beazley
+// May 5, 1997
+//
+// Python implementation
+//
+// This library provides standard typemaps for modifying SWIG's behavior.
+// With enough entries in this file, I hope that very few people actually
+// ever need to write a typemap.
+//
+// Disclaimer : Unless you really understand how typemaps work, this file
+// probably isn't going to make much sense.
+//
+
+// ------------------------------------------------------------------------
+// Pointer handling
+//
+// These mappings provide support for input/output arguments and common
+// uses for C/C++ pointers.
+// ------------------------------------------------------------------------
+
+// INPUT typemaps.
+// These remap a C pointer to be an "INPUT" value which is passed by value
+// instead of reference.
+
+/* 
+The following methods can be applied to turn a pointer into a simple
+"input" value.  That is, instead of passing a pointer to an object,
+you would use a real value instead.
+
+         int            *INPUT
+         short          *INPUT
+         long           *INPUT
+	 long long      *INPUT
+         unsigned int   *INPUT
+         unsigned short *INPUT
+         unsigned long  *INPUT
+         unsigned long long *INPUT
+         unsigned char  *INPUT
+         bool           *INPUT
+         float          *INPUT
+         double         *INPUT
+         
+To use these, suppose you had a C function like this :
+
+        double fadd(double *a, double *b) {
+               return *a+*b;
+        }
+
+You could wrap it with SWIG as follows :
+        
+        %include <typemaps.i>
+        double fadd(double *INPUT, double *INPUT);
+
+or you can use the %apply directive :
+
+        %include <typemaps.i>
+        %apply double *INPUT { double *a, double *b };
+        double fadd(double *a, double *b);
+
+*/
+
+// OUTPUT typemaps.   These typemaps are used for parameters that
+// are output only.   The output value is appended to the result as
+// a list element.
+
+/* 
+The following methods can be applied to turn a pointer into an "output"
+value.  When calling a function, no input value would be given for
+a parameter, but an output value would be returned.  In the case of
+multiple output values, they are returned in the form of a Python tuple.
+
+         int            *OUTPUT
+         short          *OUTPUT
+         long           *OUTPUT
+         long long      *OUTPUT
+         unsigned int   *OUTPUT
+         unsigned short *OUTPUT
+         unsigned long  *OUTPUT
+         unsigned long long *OUTPUT
+         unsigned char  *OUTPUT
+         bool           *OUTPUT
+         float          *OUTPUT
+         double         *OUTPUT
+         
+For example, suppose you were trying to wrap the modf() function in the
+C math library which splits x into integral and fractional parts (and
+returns the integer part in one of its parameters).K:
+
+        double modf(double x, double *ip);
+
+You could wrap it with SWIG as follows :
+
+        %include <typemaps.i>
+        double modf(double x, double *OUTPUT);
+
+or you can use the %apply directive :
+
+        %include <typemaps.i>
+        %apply double *OUTPUT { double *ip };
+        double modf(double x, double *ip);
+
+The Python output of the function would be a tuple containing both
+output values. 
+
+*/
+
+// INOUT
+// Mappings for an argument that is both an input and output
+// parameter
+
+/*
+The following methods can be applied to make a function parameter both
+an input and output value.  This combines the behavior of both the
+"INPUT" and "OUTPUT" methods described earlier.  Output values are
+returned in the form of a Python tuple.  
+
+         int            *INOUT
+         short          *INOUT
+         long           *INOUT
+         long long      *INOUT
+         unsigned int   *INOUT
+         unsigned short *INOUT
+         unsigned long  *INOUT
+         unsigned long long *INOUT
+         unsigned char  *INOUT
+         bool           *INOUT
+         float          *INOUT
+         double         *INOUT
+         
+For example, suppose you were trying to wrap the following function :
+
+        void neg(double *x) {
+             *x = -(*x);
+        }
+
+You could wrap it with SWIG as follows :
+
+        %include <typemaps.i>
+        void neg(double *INOUT);
+
+or you can use the %apply directive :
+
+        %include <typemaps.i>
+        %apply double *INOUT { double *x };
+        void neg(double *x);
+
+Unlike C, this mapping does not directly modify the input value (since
+this makes no sense in Python).  Rather, the modified input value shows
+up as the return value of the function.  Thus, to apply this function
+to a Python variable you might do this :
+
+       x = neg(x)
+
+Note : previous versions of SWIG used the symbol 'BOTH' to mark
+input/output arguments.   This is still supported, but will be slowly
+phased out in future releases.
+
+*/
+
 %include <typemaps/typemaps.swg>