diff --git a/SWIG/Doc/Manual/Contents.html b/SWIG/Doc/Manual/Contents.html index 90538976a..0f84d937a 100644 --- a/SWIG/Doc/Manual/Contents.html +++ b/SWIG/Doc/Manual/Contents.html @@ -377,6 +377,10 @@
  • Object ownership and %newobject
  • Features and the %feature directive + diff --git a/SWIG/Doc/Manual/Customization.html b/SWIG/Doc/Manual/Customization.html index 3ae99640d..51a4fa04c 100644 --- a/SWIG/Doc/Manual/Customization.html +++ b/SWIG/Doc/Manual/Customization.html @@ -18,6 +18,10 @@
  • Object ownership and %newobject
  • Features and the %feature directive + @@ -639,10 +643,90 @@ In the following example, MyExceptionClass is the name of the Java clas +

    Further details can be obtained from the Java exception handling section. +

    + +

    11.3.1 Features and default arguments

    +

    -As can be seen, the intended use for the %feature directive is as a highly flexible customization mechanism that can be used to annotate +SWIG treats methods with default arguments as separate overloaded methods as detailed +in the default arguments section. +Any %feature targeting a method with default arguments +will apply to all the extra overloaded methods that SWIG generates if the +default arguments are specified in the feature. If the default arguments are +not specified in the feature, then the feature will match that exact +wrapper method only and not the extra overloaded methods that SWIG generates. +For example: +

    + +
    +
    +%feature("except") void hello(int i=0, double d=0.0);
+void hello(int i=0, double d=0.0);
+
    +
    + +

    +will apply the feature to all three wrapper methods, that is: +

    + +
    +
    +void hello(int i, double d);
+void hello(int i);
+void hello();
+
    +
    + +

    +If the default arguments are not specified in the feature: +

    + +
    +
    +%feature("except") void hello(int i, double d);
+void hello(int i=0, double d=0.0);
+
    +
    + +

    +then the feature will only apply to this wrapper method: +

    + +
    +
    +void hello(int i, double d);
+
    +
    + +

    +and not these wrapper methods: +

    + +
    +
    +void hello(int i);
+void hello();
+
    +
    + +

    +If compactdefaultargs are being used, then the difference between +specifying or not specifying default arguments in a feature is not applicable as just one wrapper is generated. +

    + +

    +Compatibility note: The different behaviour of features specified with or without default arguments was introduced +in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed. +

    + +

    11.3.2 Feature example

    + + +

    +As has been shown earlier, the intended use for the %feature directive is as a highly flexible customization mechanism that can be used to annotate declarations with additional information for use by specific target language modules. Another example is in the Python module. You might use %feature to rewrite proxy/shadow class code as follows:

    diff --git a/SWIG/Doc/Manual/SWIGPlus.html b/SWIG/Doc/Manual/SWIGPlus.html index 9ab33d7d0..ee18b3f91 100644 --- a/SWIG/Doc/Manual/SWIGPlus.html +++ b/SWIG/Doc/Manual/SWIGPlus.html @@ -660,6 +660,11 @@ This approach allows SWIG to wrap all possible default arguments, but can be ver For example if a method has ten default arguments, then eleven wrapper methods are generated.

    +

    +Please see the Features and default arguments +section for more information on using %feature for functions with default arguments. +

    +

    Compatibility note: Versions of SWIG prior to SWIG-1.3.23 wrapped default arguments slightly differently. Instead a single wrapper method was generated and the default values were copied into the C++ wrappers