From a1c3e54ab4bd6e2258aaecc7cf2d78af1a5bba29 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Fri, 11 Jan 2013 21:59:38 +0000 Subject: [PATCH] Improvements to documentation for csdirectorin 'pre', 'post' and 'terminator' support. --- CHANGES.current | 3 + Doc/Manual/CSharp.html | 122 ++++++++++++++++++++++----------------- Doc/Manual/Contents.html | 1 + 3 files changed, 74 insertions(+), 52 deletions(-) diff --git a/CHANGES.current b/CHANGES.current index 05d533c17..e75e04dac 100644 --- a/CHANGES.current +++ b/CHANGES.current @@ -5,6 +5,9 @@ See the RELEASENOTES file for a summary of changes in each release. Version 2.0.10 (in progress) ============================ +2013-01-11: Vladimir Kalinin + [C#] Add support for csdirectorin 'pre', 'post' and 'terminator' attributes. + 2013-01-08: olly [PHP] Fix to work with a ZTS build of PHP (broken in 2.0.7). diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html index 1281f7973..6df2594c4 100644 --- a/Doc/Manual/CSharp.html +++ b/Doc/Manual/CSharp.html @@ -38,6 +38,7 @@
  • Memory management for objects passed to the C++ layer
  • Date marshalling using the csin typemap and associated attributes
  • A date example demonstrating marshalling of C# properties +
  • Date example demonstrating the 'pre' and 'post' typemap attributes for directors
  • Turning wrapped classes into partial classes
  • Extending proxy classes with additional C# code
  • Underlying type for enums @@ -201,52 +202,6 @@ For example this is needed if you change the return type to void: %typemap(ctype) Status "void" %typemap(out, null="") Status { ... } -

    -The "pre" and "post" attributes in "csdirectorin" typemap act like the same attributes in "csin" typemap. - For example if we modify Date marshalling example like this: -

    -class CDate {
-...
-  void setYear(int);
-  void setMonth(int);
-  void setDay(int);
-};
-struct Action {
-virtual void someCallback(CDate& date);
-...
-};
-
    -and declare %feature ("director") for the Action class, we would have to define additional -marshaling rules for CDate. Director typemap may look like this: -
    -%typemap(csdirectorin,
-         pre="System.DateTime temp$iminput = new System.DateTime();",
-         post="CDate temp2$iminput = new CDate($iminput, false);\n"
-              "temp2$iminput.setYear(tempdate.Year);\n"
-              "temp2$iminput.setMonth(tempdate.Month);\n"
-              "temp2$iminput.setDay(tempdate.Day);"
-         ) CDate& date "out temp$iminput"
-
    -The generated proxy class code will then contain the following wrapper for calling user-overloaded someCallback(): -
    -...
-  private void SwigDirectorsomeCallback(IntPtr date) {
-    System.DateTime tempdate = new System.DateTime();
-    try {
-      someCallback(out tempdate);
-    }
-    finally {
-    // we create managed wrapper around existing C reference, just for convenience
-      CDate temp2date = new CDate(date, false);
-      temp2date.setYear(tempdate.Year);
-      temp2date.setMonth(tempdate.Month);
-      temp2date.setDay(tempdate.Day);
-    }
-  }
-...
-
    -Pay special attention to the memory management issues, using these attributes. -

    • @@ -287,10 +242,12 @@ $jnicall -> $imcall

    Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter. The "csin" typemap supports additional optional attributes called 'cshin' and 'terminator'. +The "csdirectorin" typemap supports additional optional attributes called 'terminator'. The 'cshin' attribute should contain the parameter type and name whenever a constructor helper function is generated due to the 'pre' or 'post' attributes. The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# using or fixed block is started. Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set. Please see the Date marshalling example and Date marshalling of properties example for further understanding of these "csin" applicable attributes. +Please see the Date marshalling director example for further understanding of the "csdirectorin" attributes.

    @@ -2100,13 +2057,13 @@ The typemaps to achieve this are shown below. 
    -%typemap(cstype) const CDate& "System.DateTime"
+%typemap(cstype) const CDate & "System.DateTime"
 %typemap(csin, 
          pre="    CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);"
         ) const CDate &
          "$csclassname.getCPtr(temp$csinput)"
 
-%typemap(cstype) CDate& "out System.DateTime"
+%typemap(cstype) CDate & "out System.DateTime"
 %typemap(csin, 
          pre="    CDate temp$csinput = new CDate();", 
          post="      $csinput = new System.DateTime(temp$csinput.getYear(),"
@@ -2317,7 +2274,7 @@ Console.WriteLine("Important date: " + importantDate);

    -When SWIG wraps a variable that is a class/struct/union, it is wrapped using a pointer to the type for the reasons given in Stucture data members. +When SWIG wraps a variable that is a class/struct/union, it is wrapped using a pointer to the type for the reasons given in Structure data members. The typemap type required is thus CDate *. Given that the previous section already designed CDate * typemaps, we'll use those same typemaps plus the 'csvarin' and 'csvarout' typemaps.

    @@ -2389,8 +2346,69 @@ Some points to note:
  • The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the temp$csinput variable is such an example; it is identical to what is in the 'pre' attribute. +

    19.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors

    -

    19.8.5 Turning wrapped classes into partial classes

    + +

    +The 'pre' and 'post' attributes in the "csdirectorin" typemap act like the attributes of the same name in the "csin" typemap. +For example if we modify the Date marshalling example like this: +

    + +
    +class CDate {
+  ...
+  void setYear(int);
+  void setMonth(int);
+  void setDay(int);
+};
+struct Action {
+  virtual void someCallback(CDate &date);
+  virtual ~Action();
+  ...
+};
+
    + +

    +and declare %feature ("director") for the Action class, we would have to define additional +marshalling rules for CDate & parameter. The typemap may look like this: +

    + +
    +%typemap(csdirectorin,
+         pre="System.DateTime temp$iminput = new System.DateTime();",
+         post="CDate temp2$iminput = new CDate($iminput, false);\n"
+              "temp2$iminput.setYear(tempdate.Year);\n"
+              "temp2$iminput.setMonth(tempdate.Month);\n"
+              "temp2$iminput.setDay(tempdate.Day);"
+         ) CDate &date "out temp$iminput"
+
    + +

    +The generated proxy class code will then contain the following wrapper for calling user-overloaded someCallback(): +

    + +
    +...
+  private void SwigDirectorsomeCallback(IntPtr date) {
+    System.DateTime tempdate = new System.DateTime();
+    try {
+      someCallback(out tempdate);
+    } finally {
+      // we create a managed wrapper around the existing C reference, just for convenience
+      CDate temp2date = new CDate(date, false);
+      temp2date.setYear(tempdate.Year);
+      temp2date.setMonth(tempdate.Month);
+      temp2date.setDay(tempdate.Day);
+    }
+  }
+...
+
    +

    +Pay special attention to the memory management issues, using these attributes. +

    + + +

    19.8.6 Turning wrapped classes into partial classes

    @@ -2490,7 +2508,7 @@ demonstrating that the class contains methods calling both unmanaged code - The following example is an alternative approach to adding managed code to the generated proxy class.

    -

    19.8.6 Extending proxy classes with additional C# code

    +

    19.8.7 Extending proxy classes with additional C# code

    @@ -2529,7 +2547,7 @@ public class ExtendMe : IDisposable {

    • -

    19.8.7 Underlying type for enums

    +

    19.8.8 Underlying type for enums

    diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 74040ff0e..42e135140 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -686,6 +686,7 @@

  • Memory management for objects passed to the C++ layer
  • Date marshalling using the csin typemap and associated attributes
  • A date example demonstrating marshalling of C# properties +
  • Date example demonstrating the 'pre' and 'post' typemap attributes for directors
  • Turning wrapped classes into partial classes
  • Extending proxy classes with additional C# code
  • Underlying type for enums