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

Improve docs for %rename and C++ features like default args

Browse source
This commit is contained in:
William S Fulton 2017-09-14 18:47:12 +01:00
commit 9cc05a22f6
4 changed files with 34 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/Manual/Contents.html
View file

@ -239,8 +239,8 @@
<li><a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in overloading</a>
<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn28">Overloaded operators</a>

4
Doc/Manual/Customization.html
View file

@ -356,7 +356,7 @@ In this case, the exception handler is only attached to declarations
named "allocate". This would include both global and member
functions. The names supplied to <tt>%exception</tt> follow the same
rules as for <tt>%rename</tt> described in the section on
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>.
For example, if you wanted to define
an exception handler for a specific class, you might write this:
</p>
@ -796,7 +796,7 @@ involving <tt>%feature</tt>:
</div>
<p>
The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
section applies to all <tt>%feature</tt> directives.
In fact the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>.
The matching rules mean that features are very flexible and can be applied with

43
Doc/Manual/SWIG.html
View file

@ -1737,41 +1737,14 @@ careful about namespaces and your use of modules, you can usually
avoid these problems.</p>
<p>
<tt>%rename</tt> directive respects function parameters and <i>discriminates default parameters</i> from non-default,
which is essential for some languages including Python. Be careful renaming functions having default parameters:
When wrapping C code, simple use of identifiers/symbols with <tt>%rename</tt> usually suffices.
When wrapping C++ code, simple use of simple identifiers/symbols with <tt>%rename</tt> might be too
limiting when using C++ features such as function overloading, default arguments, namespaces, template specialization etc.
If you are using the <tt>%rename</tt> directive and C++, make sure you read the
<a href="SWIGPlus.html">SWIG and C++</a> chapter and in particular the section on
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
for method overloading and default arguments.
</p>
<div class="code"><pre>
%rename(toFFVal) to_val(FileFormat, bool bin=false);
int to_val(FileFormat flag, bool bin=false)
{
return 0;
}
%rename(toDFVal) to_val(DirFormat, bool bin);
int to_val(DirFormat flag, bool bin=false)
{
return 0;
}
%rename(toLFVal) to_val(FolderFormat, bool bin);
int to_val(FolderFormat flag, bool bin=false)
{
return 0;
}
</pre></div>
<p>
The SWIG generator yields the following warning for the last renaming:<br/>
<tt>
rename.i:36: Warning 509: Overloaded method to_val(FolderFormat) effectively ignored,<br/>
rename.i:26: Warning 509: as it is shadowed by to_val(DirFormat).<br/>
</tt>
The renaming performed for the <tt>int to_val(FolderFormat flag, bool bin)</tt>,
but not for the <tt>int to_val(FolderFormat flag)</tt>, where the second parameter <tt>bool bin</tt>
is omitted taking the default value <tt>false</tt>. See details about the default
parameters processing in the <a href="SWIGPlus.html#SWIGPlus_default_args">Default Arguments</a> section.
</p>
<p>
Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive. <tt>%ignore</tt> instructs SWIG
@ -2115,7 +2088,7 @@ except those consisting of capital letters only:
<p>
Finally, variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help
wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> section in the C++ chapter.
</p>

30
Doc/Manual/SWIGPlus.html
View file

@ -42,8 +42,8 @@
<li><a href="#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>
<ul>
<li><a href="#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_nn25">Ambiguity in overloading</a>
<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
<li><a href="#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="#SWIGPlus_nn28">Overloaded operators</a>
@ -1772,7 +1772,7 @@ public:
<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">Overloaded functions and methods</a> section.
Details of this are covered in the next section <a href="#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>.
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>
@ -1780,7 +1780,7 @@ For example if a method has ten default arguments, then eleven wrapper methods a
<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
The <a href="#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</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
@ -2031,7 +2031,7 @@ checked in the same order as they appear in this ranking.
If you're still confused, don't worry about it---SWIG is probably doing the right thing.
</p>
<H3><a name="SWIGPlus_nn25">6.15.2 Ambiguity in Overloading</a></H3>
<H3><a name="SWIGPlus_nn25">6.15.2 Ambiguity in overloading</a></H3>
<p>
@ -2149,7 +2149,7 @@ it means that the target language module has not yet implemented support for ove
functions and methods. The only way to fix the problem is to read the next section.
</p>
<H3><a name="SWIGPlus_ambiguity_resolution_renaming">6.15.3 Ambiguity resolution and renaming</a></H3>
<H3><a name="SWIGPlus_ambiguity_resolution_renaming">6.15.3 Renaming and ambiguity resolution</a></H3>
<p>
@ -2562,8 +2562,7 @@ exactly matches the wrapped method:
<p>
The C++ method can then be called from the target language with the new name no matter how many arguments are specified, for example:
<tt>newbar(2, 2.0)</tt>, <tt>newbar(2)</tt> or <tt>newbar()</tt>.
However, if the <tt>%rename</tt> does not contain the default arguments, it will only apply to the single equivalent target language overloaded method.
So if instead we have:
However, if the <tt>%rename</tt> does not contain the default arguments:
</p>
<div class="code">
@ -2572,9 +2571,24 @@ So if instead we have:
</pre>
</div>
<p>
then only one of the three equivalent overloaded methods will be renamed and wrapped as if SWIG parsed:
</p>
<div class="code">
<pre>
void Spam::newbar(int i, double d);
void Spam::bar(int i);
void Spam::bar();
</pre>
</div>
<p>
The C++ method must then be called from the target language with the new name <tt>newbar(2, 2.0)</tt> when both arguments are supplied
or with the original name as <tt>bar(2)</tt> (one argument) or <tt>bar()</tt> (no arguments).
</p>
<p>
In fact it is possible to use <tt>%rename</tt> on the equivalent overloaded methods, to rename all the equivalent overloaded methods:
</p>