Lib/csharp/arrays_csharp.i

   1 /* -----------------------------------------------------------------------------
   2  * See the LICENSE file for information on copyright, usage and redistribution
   3  * of SWIG, and the README file for authors - http://www.swig.org/release.html.
   4  *
   5  * arrays_csharp.i
   6  *
   7  * This file contains a two approaches to marshaling arrays. The first uses
   8  * default p/invoke marshaling and the second uses pinning of the arrays.
   9  *
  10  * Default marshaling approach
  11  * ----------------------------
  12  * Array typemaps using default p/invoke marshaling. The data is copied to a separately
  13  * allocated buffer when passing over the managed-native boundary.
  14  *
  15  * There are separate typemaps for in, out and inout arrays to enable avoiding
  16  * unnecessary copying.
  17  *
  18  * Example usage:
  19  *
  20  *   %include "arrays_csharp.i"
  21  *   %apply int INPUT[]  { int* sourceArray }
  22  *   %apply int OUTPUT[] { int* targetArray }
  23  *   void myArrayCopy( int* sourceArray, int* targetArray, int nitems );
  24  *
  25  *   %apply int INOUT[] { int* array1, int *array2 }
  26  *   void myArraySwap( int* array1, int* array2, int nitems );
  27  *
  28  * If handling large arrays you should consider using the pinning array typemaps
  29  * described next.
  30  *
  31  * Pinning approach
  32  * ----------------
  33  * Array typemaps using pinning. These typemaps pin the managed array given
  34  * as parameter and pass a pointer to it to the c/c++ side. This is very
  35  * efficient as no copying is done (unlike in the default array marshaling),
  36  * but it makes garbage collection more difficult. When considering using
  37  * these typemaps, think carefully whether you have callbacks that may cause
  38  * the control to re-enter the managed side from within the call (and produce
  39  * garbage for the gc) or whether other threads may produce enough garbage to
  40  * trigger gc while the call is being executed. In those cases it may be
  41  * wiser to use the default marshaling typemaps.
  42  *
  43  * Please note that when using fixed arrays, you have to mark your corresponding
  44  * module class method unsafe using
  45  * %csmethodmodifiers "public unsafe"
  46  * (the visibility of the method is up to you).
  47  *
  48  * Example usage:
  49  *
  50  *   %include "arrays_csharp.i"
  51  *   %apply int FIXED[] { int* sourceArray, int *targetArray }
  52  *   %csmethodmodifiers myArrayCopy "public unsafe";
  53  *   void myArrayCopy( int *sourceArray, int* targetArray, int nitems );
  54  *
  55  * ----------------------------------------------------------------------------- */
  56
  57 %define CSHARP_ARRAYS( CTYPE, CSTYPE )
  58
  59 // input only arrays
  60
  61 %typemap(ctype)   CTYPE INPUT[] "CTYPE*"
  62 %typemap(cstype)  CTYPE INPUT[] "CSTYPE[]"
  63 %typemap(imtype, inattributes="[In, MarshalAs(UnmanagedType.LPArray)]") CTYPE INPUT[] "CSTYPE[]"
  64 %typemap(csin)    CTYPE INPUT[] "$csinput"
  65
  66 %typemap(in)      CTYPE INPUT[] "$1 = $input;"
  67 %typemap(freearg) CTYPE INPUT[] ""
  68 %typemap(argout)  CTYPE INPUT[] ""
  69
  70 // output only arrays
  71
  72 %typemap(ctype)   CTYPE OUTPUT[] "CTYPE*"
  73 %typemap(cstype)  CTYPE OUTPUT[] "CSTYPE[]"
  74 %typemap(imtype, inattributes="[Out, MarshalAs(UnmanagedType.LPArray)]") CTYPE OUTPUT[] "CSTYPE[]"
  75 %typemap(csin)    CTYPE OUTPUT[] "$csinput"
  76
  77 %typemap(in)      CTYPE OUTPUT[] "$1 = $input;"
  78 %typemap(freearg) CTYPE OUTPUT[] ""
  79 %typemap(argout)  CTYPE OUTPUT[] ""
  80
  81 // inout arrays
  82
  83 %typemap(ctype)   CTYPE INOUT[] "CTYPE*"
  84 %typemap(cstype)  CTYPE INOUT[] "CSTYPE[]"
  85 %typemap(imtype, inattributes="[In, Out, MarshalAs(UnmanagedType.LPArray)]") CTYPE INOUT[] "CSTYPE[]"
  86 %typemap(csin)    CTYPE INOUT[] "$csinput"
  87
  88 %typemap(in)      CTYPE INOUT[] "$1 = $input;"
  89 %typemap(freearg) CTYPE INOUT[] ""
  90 %typemap(argout)  CTYPE INOUT[] ""
  91
  92 %enddef // CSHARP_ARRAYS
  93
  94 CSHARP_ARRAYS(signed char, sbyte)
  95 CSHARP_ARRAYS(unsigned char, byte)
  96 CSHARP_ARRAYS(short, short)
  97 CSHARP_ARRAYS(unsigned short, ushort)
  98 CSHARP_ARRAYS(int, int)
  99 CSHARP_ARRAYS(unsigned int, uint)
 100 // FIXME - on Unix 64 bit, long is 8 bytes but is 4 bytes on Windows 64 bit.
 101 //         How can this be handled sensibly?
 102 //         See e.g. http://www.xml.com/ldd/chapter/book/ch10.html
 103 CSHARP_ARRAYS(long, int)
 104 CSHARP_ARRAYS(unsigned long, uint)
 105 CSHARP_ARRAYS(long long, long)
 106 CSHARP_ARRAYS(unsigned long long, ulong)
 107 CSHARP_ARRAYS(float, float)
 108 CSHARP_ARRAYS(double, double)
 109
 110
 111 %define CSHARP_ARRAYS_FIXED( CTYPE, CSTYPE )
 112
 113 %typemap(ctype)   CTYPE FIXED[] "CTYPE*"
 114 %typemap(imtype)  CTYPE FIXED[] "IntPtr"
 115 %typemap(cstype)  CTYPE FIXED[] "CSTYPE[]"
 116 %typemap(csin,
 117            pre=       "    fixed ( CSTYPE* swig_ptrTo_$csinput = $csinput ) {",
 118            terminator="    }")
 119                   CTYPE FIXED[] "(IntPtr)swig_ptrTo_$csinput"
 120
 121 %typemap(in)      CTYPE FIXED[] "$1 = $input;"
 122 %typemap(freearg) CTYPE FIXED[] ""
 123 %typemap(argout)  CTYPE FIXED[] ""
 124
 125
 126 %enddef // CSHARP_ARRAYS_FIXED
 127
 128 CSHARP_ARRAYS_FIXED(signed char, sbyte)
 129 CSHARP_ARRAYS_FIXED(unsigned char, byte)
 130 CSHARP_ARRAYS_FIXED(short, short)
 131 CSHARP_ARRAYS_FIXED(unsigned short, ushort)
 132 CSHARP_ARRAYS_FIXED(int, int)
 133 CSHARP_ARRAYS_FIXED(unsigned int, uint)
 134 CSHARP_ARRAYS_FIXED(long, int)
 135 CSHARP_ARRAYS_FIXED(unsigned long, uint)
 136 CSHARP_ARRAYS_FIXED(long long, long)
 137 CSHARP_ARRAYS_FIXED(unsigned long long, ulong)
 138 CSHARP_ARRAYS_FIXED(float, float)
 139 CSHARP_ARRAYS_FIXED(double, double)
 140