jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Move C++ 'Default arguments' section in manual

Browse source
This commit is contained in:
William S Fulton 2017-09-14 07:49:06 +01:00
commit ff52610dc5
2 changed files with 115 additions and 115 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/Manual/Contents.html
View file

@ -228,7 +228,6 @@
<li><a href="SWIGPlus.html#SWIGPlus_nn12">Static members</a>
<li><a href="SWIGPlus.html#SWIGPlus_member_data">Member data</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn15">Protection</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn16">Enums and constants</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn17">Friends</a>
@ -236,6 +235,7 @@
<li><a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn20">Inheritance</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a>
<li><a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a>
<li><a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn24">Dispatch function generation</a>

228
Doc/Manual/SWIGPlus.html
View file

@ -31,7 +31,6 @@
<li><a href="#SWIGPlus_nn12">Static members</a>
<li><a href="#SWIGPlus_member_data">Member data</a>
</ul>
<li><a href="#SWIGPlus_default_args">Default arguments</a>
<li><a href="#SWIGPlus_nn15">Protection</a>
<li><a href="#SWIGPlus_nn16">Enums and constants</a>
<li><a href="#SWIGPlus_nn17">Friends</a>
@ -39,6 +38,7 @@
<li><a href="#SWIGPlus_nn19">Pass and return by value</a>
<li><a href="#SWIGPlus_nn20">Inheritance</a>
<li><a href="#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a>
<li><a href="#SWIGPlus_default_args">Default arguments</a>
<li><a href="#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a>
<ul>
<li><a href="#SWIGPlus_nn24">Dispatch function generation</a>
@ -1104,113 +1104,7 @@ a few problems related to structure wrapping and some of SWIG's
customization features.
</p>
<H2><a name="SWIGPlus_default_args">6.7 Default arguments</a></H2>
<p>
SWIG will wrap all types of functions that have default arguments. For example member functions:
</p>
<div class="code">
<pre>
class Foo {
public:
void bar(int x, int y = 3, int z = 4);
};
</pre>
</div>
<p>
SWIG handles default arguments by generating an extra overloaded method for each defaulted argument.
SWIG is effectively handling methods with default arguments as if it was wrapping the equivalent overloaded methods.
Thus for the example above, it is as if we had instead given the following to SWIG:
</p>
<div class="code">
<pre>
class Foo {
public:
void bar(int x, int y, int z);
void bar(int x, int y);
void bar(int x);
};
</pre>
</div>
<p>
The wrappers produced are exactly the same as if the above code was instead fed into SWIG.
Details of this are covered later in the <a href="#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a> section.
This approach allows SWIG to wrap all possible default arguments, but can be verbose.
For example if a method has ten default arguments, then eleven wrapper methods are generated.
</p>
<p>
Please see the <a href="Customization.html#Customization_features_default_args">Features and default arguments</a>
section for more information on using <tt>%feature</tt> with functions with default arguments.
The <a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section
also deals with using <tt>%rename</tt> and <tt>%ignore</tt> on methods with default arguments.
If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a <tt>typecheck</tt> typemap.
See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> section for details or otherwise
use the <tt>compactdefaultargs</tt> feature flag as mentioned below.
</p>
<p>
<b>Compatibility note:</b> 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
so that the method being wrapped was then called with all the arguments specified.
If the size of the wrappers are a concern then this approach to wrapping methods with default arguments
can be re-activated by using the <tt>compactdefaultargs</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a>.
</p>
<div class="code">
<pre>
%feature("compactdefaultargs") Foo::bar;
class Foo {
public:
void bar(int x, int y = 3, int z = 4);
};
</pre>
</div>
<p>
This is great for reducing the size of the wrappers, but the caveat is it does not work for the statically typed languages,
such as C# and Java,
which don't have optional arguments in the language,
Another restriction of this feature is that it cannot handle default arguments that are not public.
The following example illustrates this:
</p>
<div class="code">
<pre>
class Foo {
private:
static const int spam;
public:
void bar(int x, int y = spam); // Won't work with %feature("compactdefaultargs") -
// private default value
};
</pre>
</div>
<p>
This produces uncompilable wrapper code because default values in C++ are
evaluated in the same scope as the member function whereas SWIG
evaluates them in the scope of a wrapper function (meaning that the
values have to be public).
</p>
<p>
The <tt>compactdefaultargs</tt> feature is automatically turned on when wrapping <a href="SWIG.html#SWIG_default_args">C code with default arguments</a>.
Some target languages will also automatically turn on this feature
if the keyword arguments feature (kwargs) is specified for either C or C++ functions, and the target language supports kwargs,
the <tt>compactdefaultargs</tt> feature is also automatically turned on.
Keyword arguments are a language feature of some scripting languages, for example Ruby and Python.
SWIG is unable to support kwargs when wrapping overloaded methods, so the default approach cannot be used.
</p>
<H2><a name="SWIGPlus_nn15">6.8 Protection</a></H2>
<H2><a name="SWIGPlus_nn15">6.7 Protection</a></H2>
<p>
@ -1230,7 +1124,7 @@ until you explicitly give a `<tt>public:</tt>' declaration (This is
the same convention used by C++).
</p>
<H2><a name="SWIGPlus_nn16">6.9 Enums and constants</a></H2>
<H2><a name="SWIGPlus_nn16">6.8 Enums and constants</a></H2>
<p>
@ -1260,7 +1154,7 @@ Swig_STOUT = Swig::STOUT
Members declared as <tt>const</tt> are wrapped as read-only members and do not create constants.
</p>
<H2><a name="SWIGPlus_nn17">6.10 Friends</a></H2>
<H2><a name="SWIGPlus_nn17">6.9 Friends</a></H2>
<p>
@ -1321,7 +1215,7 @@ namespace bar {
and a wrapper for the method 'blah' will not be generated.
</p>
<H2><a name="SWIGPlus_nn18">6.11 References and pointers</a></H2>
<H2><a name="SWIGPlus_nn18">6.10 References and pointers</a></H2>
<p>
@ -1421,7 +1315,7 @@ templates and the STL. This was first added in SWIG-1.3.12.
</p>
<H2><a name="SWIGPlus_nn19">6.12 Pass and return by value</a></H2>
<H2><a name="SWIGPlus_nn19">6.11 Pass and return by value</a></H2>
<p>
@ -1525,7 +1419,7 @@ classes that don't define a default constructor.
It is not used for C++ pointers or references.
</p>
<H2><a name="SWIGPlus_nn20">6.13 Inheritance</a></H2>
<H2><a name="SWIGPlus_nn20">6.12 Inheritance</a></H2>
<p>
@ -1711,7 +1605,7 @@ functions for virtual members that are already defined in a base
class.
</p>
<H2><a name="SWIGPlus_nn21">6.14 A brief discussion of multiple inheritance, pointers, and type checking</a></H2>
<H2><a name="SWIGPlus_nn21">6.13 A brief discussion of multiple inheritance, pointers, and type checking</a></H2>
<p>
@ -1843,6 +1737,112 @@ int y = B_function((B *) pB);
In practice, the pointer is held as an integral number in the target language proxy class.
</p>
<H2><a name="SWIGPlus_default_args">6.14 Default arguments</a></H2>
<p>
SWIG will wrap all types of functions that have default arguments. For example member functions:
</p>
<div class="code">
<pre>
class Foo {
public:
void bar(int x, int y = 3, int z = 4);
};
</pre>
</div>
<p>
SWIG handles default arguments by generating an extra overloaded method for each defaulted argument.
SWIG is effectively handling methods with default arguments as if it was wrapping the equivalent overloaded methods.
Thus for the example above, it is as if we had instead given the following to SWIG:
</p>
<div class="code">
<pre>
class Foo {
public:
void bar(int x, int y, int z);
void bar(int x, int y);
void bar(int x);
};
</pre>
</div>
<p>
The wrappers produced are exactly the same as if the above code was instead fed into SWIG.
Details of this are covered later in the <a href="#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a> section.
This approach allows SWIG to wrap all possible default arguments, but can be verbose.
For example if a method has ten default arguments, then eleven wrapper methods are generated.
</p>
<p>
Please see the <a href="Customization.html#Customization_features_default_args">Features and default arguments</a>
section for more information on using <tt>%feature</tt> with functions with default arguments.
The <a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section
also deals with using <tt>%rename</tt> and <tt>%ignore</tt> on methods with default arguments.
If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a <tt>typecheck</tt> typemap.
See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> section for details or otherwise
use the <tt>compactdefaultargs</tt> feature flag as mentioned below.
</p>
<p>
<b>Compatibility note:</b> 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
so that the method being wrapped was then called with all the arguments specified.
If the size of the wrappers are a concern then this approach to wrapping methods with default arguments
can be re-activated by using the <tt>compactdefaultargs</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a>.
</p>
<div class="code">
<pre>
%feature("compactdefaultargs") Foo::bar;
class Foo {
public:
void bar(int x, int y = 3, int z = 4);
};
</pre>
</div>
<p>
This is great for reducing the size of the wrappers, but the caveat is it does not work for the statically typed languages,
such as C# and Java,
which don't have optional arguments in the language,
Another restriction of this feature is that it cannot handle default arguments that are not public.
The following example illustrates this:
</p>
<div class="code">
<pre>
class Foo {
private:
static const int spam;
public:
void bar(int x, int y = spam); // Won't work with %feature("compactdefaultargs") -
// private default value
};
</pre>
</div>
<p>
This produces uncompilable wrapper code because default values in C++ are
evaluated in the same scope as the member function whereas SWIG
evaluates them in the scope of a wrapper function (meaning that the
values have to be public).
</p>
<p>
The <tt>compactdefaultargs</tt> feature is automatically turned on when wrapping <a href="SWIG.html#SWIG_default_args">C code with default arguments</a>.
Some target languages will also automatically turn on this feature
if the keyword arguments feature (kwargs) is specified for either C or C++ functions, and the target language supports kwargs,
the <tt>compactdefaultargs</tt> feature is also automatically turned on.
Keyword arguments are a language feature of some scripting languages, for example Ruby and Python.
SWIG is unable to support kwargs when wrapping overloaded methods, so the default approach cannot be used.
</p>
<H2><a name="SWIGPlus_overloaded_methods">6.15 Wrapping Overloaded Functions and Methods</a></H2>