diff options
Diffstat (limited to 'Doc/Manual/SWIGPlus.html')
| -rw-r--r-- | Doc/Manual/SWIGPlus.html | 625 |
1 files changed, 512 insertions, 113 deletions
diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index dc9ae0f7e..17cfde3b5 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -34,6 +34,12 @@ <li><a href="#SWIGPlus_nn15">Protection</a> <li><a href="#SWIGPlus_nn16">Enums and constants</a> <li><a href="#SWIGPlus_nn17">Friends</a> +<ul> +<li><a href="#SWIGPlus_friend_classes">Friend classes</a> +<li><a href="#SWIGPlus_friend_function_definitions">Friend function definitions</a> +<li><a href="#SWIGPlus_friend_function_declarations">Friend function declarations</a> +<li><a href="#SWIGPlus_friends_unqualified">Unqualified friend functions</a> +</ul> <li><a href="#SWIGPlus_nn18">References and pointers</a> <li><a href="#SWIGPlus_nn19">Pass and return by value</a> <li><a href="#SWIGPlus_nn20">Inheritance</a> @@ -48,12 +54,16 @@ </ul> <li><a href="#SWIGPlus_nn28">Overloaded operators</a> <li><a href="#SWIGPlus_class_extension">Class extension</a> +<ul> +<li><a href="#SWIGPlus_replacing_methods">Replacing class methods</a> +</ul> <li><a href="#SWIGPlus_nn30">Templates</a> <ul> <li><a href="#SWIGPlus_template_directive">The %template directive</a> <li><a href="#SWIGPlus_template_functions">Function templates</a> <li><a href="#SWIGPlus_template_classes">Default template arguments</a> <li><a href="#SWIGPlus_template_class_inheritance">Template base classes</a> +<li><a href="#SWIGPlus_template_empty">Empty template instantiation</a> <li><a href="#SWIGPlus_template_specialization">Template specialization</a> <li><a href="#SWIGPlus_template_member">Member templates</a> <li><a href="#SWIGPlus_template_scoping">Scoping and templates</a> @@ -89,8 +99,9 @@ This chapter describes SWIG's support for wrapping C++. It is mostly concerned about C++ as defined by the C++ 98 and 03 standards. For additions to the original C++ standard, please read the <a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a>, -<a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a> and -<a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a> chapters. +<a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a>, +<a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a> and +<a href="CPlusPlus20.html#CPlusPlus20">SWIG and C++20</a> chapters. As a prerequisite, you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see how SWIG wraps ISO C. Support for C++ builds upon ISO C @@ -250,7 +261,7 @@ details. The SWIG Wiki also has further details. </p> <b>Compatibility Note:</b> Early versions of SWIG generated just a flattened low-level C style API to C++ classes by default. -The <tt>-noproxy</tt> commandline option is recognised by many target languages and will generate just this +The <tt>-noproxy</tt> commandline option is recognised by some target languages and will generate just this interface as in earlier versions. <H2><a name="SWIGPlus_nn38">6.5 Proxy classes</a></H2> @@ -580,7 +591,7 @@ automatically generate a wrapper for one. <li> If a C++ class does not declare an explicit copy constructor, SWIG will -automatically generate a wrapper for one if the <tt>%copyctor</tt> is used. +automatically generate a wrapper for one if <tt>%copyctor</tt> is used. </li> <li> @@ -687,8 +698,7 @@ class Foo { // No destructor is generated, unless one is declared <b>Compatibility Note:</b> The generation of default constructors/implicit destructors was made the default behavior in SWIG 1.3.7. This may break certain older modules, but the old behavior can -be easily restored using <tt>%nodefault</tt> or the -<tt>-nodefault</tt> command line option. Furthermore, in order for +be easily restored using <tt>%nodefault</tt>. Furthermore, in order for SWIG to properly generate (or not generate) default constructors, it must be able to gather information from both the <tt>private</tt> and <tt>protected</tt> sections (specifically, it needs to know if a private or @@ -702,9 +712,9 @@ those sections in the interface or using <tt>%nodefault</tt> to fix the problem. <p> <b>Note:</b> The <tt>%nodefault</tt> -directive/<tt>-nodefault</tt> options described above, which disable both the default +directive described above, which disables both the default constructor and the implicit destructors, could lead to memory -leaks, and so it is strongly recommended to not use them. +leaks, and so it is strongly recommended to not use it. </p> @@ -870,10 +880,12 @@ could be wrapped, but they had to be renamed. For example: <div class="code"> <pre> +%rename(CopyFoo) Foo::Foo(const Foo &); + class Foo { public: Foo(); - %name(CopyFoo) Foo(const Foo &); + Foo(const Foo &); ... }; </pre> @@ -1084,13 +1096,6 @@ typemaps, eg <tt>%apply const std::string & { std::string * }</tt>, but this </p> <p> -<b>Compatibility note:</b> Read-only access used to be controlled by a pair of directives -<tt>%readonly</tt> and <tt>%readwrite</tt>. Although these directives still work, they -generate a warning message. Simply change the directives to <tt>%immutable;</tt> and -<tt>%mutable;</tt> to silence the warning. Don't forget the extra semicolon! -</p> - -<p> <b>Compatibility note:</b> Prior to SWIG-1.3.12, all members of unknown type were wrapped into accessor functions using pointers. For example, if you had a structure like this @@ -1121,7 +1126,7 @@ customization features. <p> SWIG wraps class members that are public following the C++ conventions, i.e., by explicit public declaration or by the use of - the <tt>using</tt> directive. In general, anything specified in a + <tt>using</tt> declarations. In general, anything specified in a private or protected section will be ignored, although the internal code generator sometimes looks at the contents of the private and protected sections so that it can properly generate code for default @@ -1168,64 +1173,218 @@ Members declared as <tt>const</tt> are wrapped as read-only members and do not c <H2><a name="SWIGPlus_nn17">6.9 Friends</a></H2> +<H3><a name="SWIGPlus_friend_classes">6.9.1 Friend classes</a></H3> + + <p> -Friend declarations are recognised by SWIG. For example, if -you have this code: +Friend classes are a C++ feature that do not affect SWIG wrappers. +SWIG simply parses the friend class declarations, but they are effectively ignored +as they have no meaningful effect for wrappers. +An example of friend classes: </p> <div class="code"> <pre> -class Foo { -public: +class X; +class Y; +class C { + // Friend classes have no effect on generated wrappers + friend class X; + friend Y; ... - friend void blah(Foo *f); +}; +</pre> +</div> + +<H3><a name="SWIGPlus_friend_function_definitions">6.9.2 Friend function definitions</a></H3> + + +<p> +A friend function definition in a C++ class defines a non-member function of the class +and simultaneously makes it a friend of the class. +For example, if you have this code: +</p> + +<div class="code"> +<pre> +class Buddy { + int val; + friend int blah(Buddy *b) { return b->val; } +public: ... }; </pre> </div> <p> -then the <tt>friend</tt> declaration does result in a wrapper code -equivalent to one generated for the following declaration +then the <tt>friend</tt> function definition results in wrapper code +equivalent to one generated for the following: </p> <div class="code"> <pre> -class Foo { +class Buddy { + int val; + friend int blah(Buddy *b); public: ... }; -void blah(Foo *f); +int blah(Buddy *b) { return b->val; } </pre> </div> <p> -A friend declaration, as in C++, is understood to be in the same scope -where the class is declared, hence, you can have +Access from target languages is thus as if <tt>blah</tt> was wrapped as a non-member function. +The function is available and wrapped even if the friend is defined with private or protected access. +</p> + +<p> +A friend definition, as in C++, is understood to be in the same scope +that the class is defined in, hence the scoping required for SWIG directives, such as <tt>%ignore</tt>, is as follows: </p> <div class="code"> <pre> - -%ignore bar::blah(Foo *f); +%ignore bar::blah(Buddy *b); +// Not: %ignore bar::Buddy::blah(Buddy *b); namespace bar { - - class Foo { + class Buddy { + int val; + friend int blah(Buddy *b) { return b->val; } public: ... - friend void blah(Foo *f); - ... }; } </pre> </div> <p> -and a wrapper for the method 'blah' will not be generated. +and a wrapper for <tt>blah</tt> will not be generated. +</p> + +<H3><a name="SWIGPlus_friend_function_declarations">6.9.3 Friend function declarations</a></H3> + + +<p> +A C++ class can specify friends via friend function declarations. +These functions are allowed access to the private and protected members of a class. +This is pure C++ functionality and these friend function declarations are hence quietly ignored by SWIG and do not result in any wrappers. +Well, not always! The C++ rules for friends that SWIG needs to follow are not that simple. +Technically, only qualified function declarations are silently ignored by SWIG. +Below are some examples of qualified friend declarations in <tt>A</tt> that are quietly ignored: +</p> + +<div class="code"> +<pre> +struct B { + int f(); + B(); + ~B(); + ... +}; + +int g(); + +class A { +public: + // The following friend function-declarations are silently ignored (including constructor and destructor friends) + friend B::B(); + friend B::~B(); + friend int B::f(); + friend int ::g(); + ... +}; +</pre> +</div> + +<p> +In the example above, if SWIG parses the struct <tt>B</tt> and global function <tt>g()</tt>, +then they are of course wrapped as normal. +</p> + + +<H3><a name="SWIGPlus_friends_unqualified">6.9.4 Unqualified friend functions</a></H3> + + +<p> +Further clarification is required regarding both friend function definitions and declarations. +In C++, friend function definitions can only be unqualified, whereas, friend function declarations can be either unqualified or qualified. Qualified friend function declarations are silently ignored by SWIG as covered in the previous section. SWIG does generate wrappers for any unqualified friend functions that it parses. This section goes through some of the complexities of wrapping unqualified friend functions. +</p> + +<p> +Consider an unqualified friend function definition: +</p> + +<div class="code"> +<pre> +class Chum { + int val; + friend int blah() { Chum c; c.private_function(); return c.val; } + void private_function(); +public: + ... +}; +</pre> +</div> + +<p> +The <tt>Chum::blah()</tt> friend is very similar to the <tt>Buddy::blah(Buddy *)</tt> friend presented earlier. +However, the generated code to call <tt>blah()</tt> may not compile unlike the code to call <tt>blah(Buddy *)</tt>. +The compiler error will be something like: + +<div class="shell"> +<pre> +error: 'blah' was not declared in this scope +</pre> +</div> + +<p> +The reason one works and the other doesn't is due to the rules around unqualified friend definitions/declarations. Broadly, friends are not visible for lookup except via argument dependent lookup that considers the class that the friend is defined/declared in, unless there is a <i>matching declaration</i> at namespace scope. +This will probably only make sense if you are conversant with this C++ concept, which is covered quite well at <a href="https://en.cppreference.com/w/cpp/language/adl">Argument-dependent lookup</a>. +In our examples, <tt>blah(Buddy *)</tt> is visible via argument dependent lookup, but <tt>blah()</tt> is not. The solution is thus to provide a <i>matching declaration</i> in order to make the function visible to the compiler. Simply add: +</p> + +<div class="code"> +<pre> +int blah(); +</pre> +</div> + +<p> +SWIG does <b>not</b> have to parse it. In all likelihood, your code already has the <i>matching declaration</i> as it is required in order for the friend function definition to be usable from pure C++ code. </p> +<p> +The same potential problem applies to unqualified friend function declarations, such as: +</p> + +<div class="code"> +<pre> +class Mate { + int val; + friend int blah(); // Unqualified friend function declaration + void private_function(); +public: + ... +}; +</pre> +</div> + +<p> +Again, the actual function declaration needs to be visible to the compiler. +Or just the actual function definition as shown below. +This must be defined in the same scope as <tt>Mate</tt>. +Of course the function definition is necessary in order to avoid linking issues too. +</p> + +<div class="code"> +<pre> +int blah() { Mate m; m.private_function(); return m.val; } +</pre> +</div> + <H2><a name="SWIGPlus_nn18">6.10 References and pointers</a></H2> @@ -1348,16 +1507,19 @@ following: <div class="code"> <pre> Vector *wrap_cross_product(Vector *a, Vector *b) { - Vector x = *a; - Vector y = *b; - Vector r = cross_product(x, y); + Vector x; + Vector y; + Vector r; + x = *a; + y = *b; + r = cross_product(x, y); return new Vector(r); }</pre> </div> <p> -In order for the wrapper code to compile, <tt>Vector</tt> must define a copy constructor and a -default constructor. +In order for the wrapper code to compile, <tt>Vector</tt> must define a default constructor, copy assignment operator (and/or a move assignment operator for C++11 and later). +The <a href="CPlusPlus11.html#CPlusPlus11_move_only">Movable and move-only types</a> section should be read regarding C++11 move semantics and return by value. </p> <p> @@ -1370,9 +1532,12 @@ called the "Fulton Transform". This produces a wrapper that looks like this: <div class="code"> <pre> Vector cross_product(Vector *a, Vector *b) { - SwigValueWrapper<Vector> x = *a; - SwigValueWrapper<Vector> y = *b; - SwigValueWrapper<Vector> r = cross_product(x, y); + SwigValueWrapper<Vector> x; + SwigValueWrapper<Vector> y; + SwigValueWrapper<Vector> r; + x = *a; + y = *b; + r = cross_product(x, y); return new Vector(r); } </pre> @@ -1799,6 +1964,11 @@ use the <tt>compactdefaultargs</tt> feature flag as mentioned below. </p> <p> +For C# please see the <a href="CSharp.html#CSharp_named_arguments">C# named and optional arguments</a> section for information on special +handling of default arguments available specifically for C#. +</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. @@ -1824,6 +1994,7 @@ 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"> @@ -2079,7 +2250,6 @@ or for statically typed languages like Java: <pre> example.i:4: Warning 516: Overloaded method foo(long) ignored, example.i:3: Warning 516: using foo(int) instead. -at example.i:3 used. </pre> </div> @@ -2138,7 +2308,7 @@ This error means that the target language module supports overloading, but for some reason there is no type-checking rule that can be used to generate a working dispatch function. The resulting behavior is then undefined. You should report this as a bug to the -<a href="http://www.swig.org/bugs.html">SWIG bug tracking database</a> +<a href="https://www.swig.org/bugs.html">SWIG bug tracking database</a> if this is due to one of the typemaps supplied with SWIG. </p> @@ -2315,7 +2485,7 @@ members (of all classes): Note: the <tt>*::</tt> syntax is non-standard C++, but the '*' is meant to be a wildcard that matches any class name (we couldn't think of a better alternative so if you have a better idea, send email to -the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a>. +the <a href="https://www.swig.org/mail.html">swig-devel mailing list</a>. </p> <p> @@ -2326,8 +2496,8 @@ also apply to <tt>%ignore</tt>. For example: <div class="code"> <pre> %ignore foo(double); // Ignore all foo(double) -%ignore Spam::foo; // Ignore foo in class Spam -%ignore Spam::foo(double); // Ignore foo(double) in class Spam +%ignore Spam::foo; // Ignore foo in class Spam (and foo in any derived classes) +%ignore Spam::foo(double); // Ignore foo(double) in class Spam (and foo in any derived classes) %ignore *::foo(double); // Ignore foo(double) in all classes </pre> </div> @@ -2383,6 +2553,53 @@ over a renaming of <tt>foo(int)</tt>).</p> </li> <li><p> +Renaming a class member, using an unparameterized but qualified name, such as <tt>Spam::foo</tt>, also applies to members in all derived classes +that have members with the same name. +This can be used to simply rename a method, across an entire class hierarchy for all overloaded and non-overloaded methods. +This also applies to methods introduced via <tt>using</tt> declarations, see +<a href="#SWIGPlus_nn35">Using declarations and inheritance</a>. +For example: +</p> + +<div class="code"> +<pre> +%rename(foo_new) Spam::foo; + +class Spam { +public: + virtual void foo(int); // Renamed to foo_new +}; + +class Bar : public Spam { +public: + virtual void foo(int); // Renamed to foo_new + void foo(bool, short, int); // Renamed to foo_new +}; + +class Grok : public Bar { +public: + virtual void foo(int); // Renamed to foo_new + void foo(bool, int); // Renamed to foo_new + void foo(const char *); // Renamed to foo_new + void foo(Bar *); // Renamed to foo_new +}; + +class Spok : public Grok { +public: + void foo(); // Renamed to foo_new +}; + +class Knock : public Spok { +public: + using Grok::foo; // Introduced methods renamed to foo_new +}; +</pre> +</div> + +</li> + + +<li><p> The order in which <tt>%rename</tt> directives are defined does not matter as long as they appear before the declarations to be renamed. Thus, there is no difference between saying:</p> @@ -2936,13 +3153,59 @@ as its use with C structures. Please refer to the <a href="SWIG.html#SWIG_adding section for further details. </p> +<H3><a name="SWIGPlus_replacing_methods">6.17.1 Replacing class methods</a></H3> + + +<p> +Suppose there is a method in a class that you need to replace and keep the method name the same. +This can be achieved combining the <tt>%extend</tt> and <tt>%ignore</tt> directives covered earlier. +Here is an example to replace the <tt>MyClass::mymethod()</tt>: + +<div class="code"> +<pre> +%extend MyClass { + void mymethod() { + std::cout << "swig mymethod" << std::endl; + } +} + +%ignore MyClass::mymethod; + +%inline %{ +class MyClass { +public: + void mymethod() { + std::cout << "class mymethod" << std::endl; + } +}; +%} +</pre> +</div> + <p> -<b>Compatibility note:</b> The <tt>%extend</tt> directive is a new -name for the <tt>%addmethods</tt> directive in SWIG1.1. Since <tt>%addmethods</tt> could -be used to extend a structure with more than just methods, a more suitable -directive name has been chosen. +Or if your code organization makes more sense to put +the <tt>%extend</tt> after the class definition, you would need the following: </p> +<div class="code"> +<pre> +%rename("") MyClass::mymethod; // unignores the method +</pre> +</div> + +<p> +before the <tt>%extend</tt> or SWIG will continue to ignore +<tt>mymethod()</tt>, even in an <tt>%extend</tt>. +</p> + +<p> +Note that you can call the class method from the method +in <tt>%extend</tt>, just use <tt>self->mymethod()</tt> and it will call +the class method, not the one in <tt>%extend</tt>. +</p> + + + <H2><a name="SWIGPlus_nn30">6.18 Templates</a></H2> @@ -2954,22 +3217,24 @@ is expected in an interface file. For example: <div class="code"> <pre> void foo(vector<int> *a, int n); -void bar(list<int, 100> *x); +void bar(std::array<int, 100> *x); </pre> </div> <p> There are some restrictions on the use of non-type arguments. Simple literals -are supported, and so are some constant expressions. However, use of '<' -and '>' within a constant expressions currently is not supported by SWIG -('<=' and '>=' are though). For example: +are supported, and so are most constant expressions. However, there are some +limitations on the use of '<' and '>' in constant expressions (but note +that '<=' and '>=' are fully supported). For example: </p> <div class="code"> <pre> -void bar(list<int, 100> *x); // OK -void bar(list<int, 2*50> *x); // OK -void bar(list<int, (2>1 ? 100 : 50)> *x) // Not supported +void bar(std::array<int, 100> *x); // OK +void bar(std::array<int, 2*50> *x); // OK +void bar(std::array<int, (1<2 ? 100 : 50)> *x) // OK +void bar(std::array<int, 1<2 ? 100 : 50> *x) // Not supported +void bar(std::array<int, (2>1 ? 100 : 50)> *x) // Not supported </pre> </div> @@ -3150,10 +3415,28 @@ void foo(List<Integer> *x); In this case, <tt>List<Integer></tt> is exactly the same type as <tt>List<int></tt>. Any use of <tt>List<Integer></tt> is mapped back to the instantiation of <tt>List<int></tt> created earlier. Therefore, it is -not necessary to instantiate a new class for the type <tt>Integer</tt> (doing so is -redundant and will simply result in code bloat). +not correct to instantiate a new class for the type <tt>Integer</tt>. +An attempt to do so such as: </p> +<div class="code"> +<pre> +%template(intList) List<int>; +%template(IntegerList) List<Integer>; // Ignored +</pre> +</div> + +<p> +will result in the duplicate instantiation being ignored with a warning: +</p> + +<div class="shell"> +<pre> +example.i:48: Warning 404: Duplicate template instantiation of 'List< Integer >' with name 'IntegerList' ignored, +example.i:47: Warning 404: previous instantiation of 'List< int >' with name 'intList'. +</pre> +</div> + <p> The template provided to <tt>%template</tt> for instantiation must be the actual template and not a typedef to a template. </p> @@ -3222,36 +3505,49 @@ original template definition. Template default arguments are supported. For ex <div class="code"> <pre> -template vector<typename T, int max=100> class vector { +template <typename T, int max=100> class vector { ... }; -%template(intvec) vector<int>; // OK +%template(intvec) vector<int>; // OK %template(vec1000) vector<int, 1000>; // OK </pre> </div> <p> The <tt>%template</tt> directive should not be used to wrap the same -template instantiation more than once in the same scope. This will -generate an error. For example: +template instantiation more than once. This also applies to default parameters +where a template parameter specified in the instantiation is the same as the default parameter. +For example: </p> <div class="code"> <pre> -%template(intList) List<int>; -%template(Listint) List<int>; // Error. Template already wrapped. +%template(vec) vector<double>; // OK +%template(vec100) vector<double, 100>; // Ignored </pre> </div> <p> -This error is caused because the template expansion results in two -identical classes with the same name. This generates a symbol table -conflict. Besides, it probably more efficient to only wrap a specific -instantiation only once in order to reduce the potential for code -bloat. +will warn: </p> +<div class="shell"> +<pre> +example.i:59: Warning 404: Duplicate template instantiation of 'vector< double,100 >' with name 'vec100' ignored, +example.i:58: Warning 404: previous instantiation of 'vector< double >' with name 'vec'. +</pre> +</div> + +<p> +If this was not ignored, the template expansion would result in two identical classes. +An identical instantiation is only wrapped once in order to reduce code bloat. +</p> + +<p> +<b>Compatibility Note</b>: Versions prior to SWIG-4.2.0 would sometimes not detect and prevent duplicate +instantiations, such as when the wrapped name was different. +</p> <H3><a name="SWIGPlus_template_class_inheritance">6.18.4 Template base classes</a></H3> @@ -3319,20 +3615,6 @@ Don't worry--if you get the order wrong, SWIG should generate a warning message. </p> <p> -Occasionally, you may need to tell SWIG about base classes that are defined by templates, -but which aren't supposed to be wrapped. Since SWIG is not able to automatically -instantiate templates for this purpose, you must do it manually. To do this, simply -use the empty template instantiation, that is, <tt>%template</tt> with no name. For example: -</p> - -<div class="code"> -<pre> -// Instantiate traits<double, double>, but don't wrap it. -%template() traits<double, double>; -</pre> -</div> - -<p> If you have to instantiate a lot of different classes for many different types, you might consider writing a SWIG macro. For example: </p> @@ -3357,7 +3639,66 @@ TEMPLATE_WRAP(PairStringInt, std::pair<string, int>) Note the use of a vararg macro for the type T. If this wasn't used, the comma in the templated type in the last example would not be possible. </p> -<H3><a name="SWIGPlus_template_specialization">6.18.5 Template specialization</a></H3> +<H3><a name="SWIGPlus_template_empty">6.18.5 Empty template instantiation</a></H3> + + +<p> +Occasionally, you may need to tell SWIG about classes that are defined by templates, +but which aren't supposed to be wrapped. Since SWIG is not able to automatically +instantiate templates for this purpose, you must do it manually. To do this, simply +use <tt>%template()</tt>, that is the empty template instantiation that omits providing a name. For example: +</p> + +<div class="code"> +<pre> +template<typename T> struct Traits { + typedef T type; +}; +%} + +%template() Traits<int>; // instantiate Traits<int>, but don't wrap it + +void traitor(Traits<int>::type val); +</pre> +</div> + +<p> +Without a template instantiation, SWIG does not know that the first parameter to the <tt>traitor</tt> +function is type int and passing an integer to this function from any target language won't work. +The empty template instantiation adds the appropriate type information into SWIG's type system, without +forcing one to wrap the <tt>Traits</tt> class. +</p> + +<p> +Duplicate template instantiation are not allowed, as described in the +<a href="#SWIGPlus_template_classes">Default template arguments</a> section above. +There is one exception where a named template instantiation can be followed by an empty template instantiation. +Duplicate empty template instantiations are silently ignored, unlike duplicate named template instantiations. +</p> + +<p> +Unlike template class instantiations, template function instantiations must have a name. +Consider the following: +</p> + +<div class="code"> +<pre> +template<class T> T tfunc(T x) { }; +%template() tfunc<double>; +</pre> +</div> + +<p> +The empty template instantiation will be ignored with: +</p> + +<div class="shell"> +<pre> +example.i:9: Warning 519: %template() contains no name. Template method ignored: tfunc< double >(double) +</pre> +</div> + +<H3><a name="SWIGPlus_template_specialization">6.18.6 Template specialization</a></H3> <p> @@ -3447,7 +3788,7 @@ SWIG implements template argument deduction so that the following partial specia </pre> </div> -<H3><a name="SWIGPlus_template_member">6.18.6 Member templates</a></H3> +<H3><a name="SWIGPlus_template_member">6.18.7 Member templates</a></H3> <p> @@ -3631,7 +3972,7 @@ Alternatively, you could expand the constructor template in selected instantiati // Create default and conversion constructors %extend pair<double, double> { - %template(paird) pair<double, dobule>; // Default constructor + %template(paird) pair<double, double>; // Default constructor %template(pairc) pair<int, int>; // Conversion constructor }; </pre> @@ -3646,7 +3987,7 @@ instead: <pre> // Create default and conversion constructors %extend pair<double, double> { - %template(pair) pair<double, dobule>; // Default constructor + %template(pair) pair<double, double>; // Default constructor %template(pair) pair<int, int>; // Conversion constructor }; </pre> @@ -3659,7 +4000,7 @@ constructor, that will dispatch the proper call depending on the argument type. </p> -<H3><a name="SWIGPlus_template_scoping">6.18.7 Scoping and templates</a></H3> +<H3><a name="SWIGPlus_template_scoping">6.18.8 Scoping and templates</a></H3> <p> @@ -3760,7 +4101,7 @@ template class C<int>; </p> -<H3><a name="SWIGPlus_template_more">6.18.8 More on templates</a></H3> +<H3><a name="SWIGPlus_template_more">6.18.9 More on templates</a></H3> <p> @@ -4016,23 +4357,23 @@ math::Complex c; <p> At this level, namespaces are relatively easy to manage. However, things start to get very ugly when you throw in the other ways a namespace can be used. For example, -selective symbols can be exported from a namespace with <tt>using</tt>. +selective symbols can be exported from a namespace with a <tt>using</tt> declaration: </p> <div class="code"> <pre> -using math::Complex; +using math::Complex; // Using declaration double magnitude(Complex *c); // Namespace prefix stripped </pre> </div> <p> -Similarly, the contents of an entire namespace can be made available like this: +Similarly, the contents of an entire namespace can be made available via a <tt>using</tt> directive: </p> <div class="code"> <pre> -using namespace math; +using namespace math; // Using directive double x = sin(1.0); double magnitude(Complex *c); </pre> @@ -4162,8 +4503,8 @@ When this conflict occurs, you will get an error message that resembles this: <div class="shell"> <pre> -example.i:26. Error. 'foo' is multiply defined in the generated target language module. -example.i:23. Previous declaration of 'foo' +example.i:26: Error: 'foo' is multiply defined in the generated target language module. +example.i:23: Error: Previous declaration of 'foo' </pre> </div> @@ -4189,9 +4530,11 @@ Similarly, <tt>%ignore</tt> can be used to ignore declarations. </p> <p> -<tt>using</tt> declarations do not have any effect on the generated wrapper -code. They are ignored by SWIG language modules and they do not result in any -code. However, these declarations <em>are</em> used by the internal type +C++ <tt>using</tt> directives and <tt>using</tt> declarations +do not add any code to the generated wrapper code. +However, there is an exception in one context, see <a href="#SWIGPlus_nn35">Using declarations and inheritance</a> +for introducing members of a base class into a derived class definition. +C++ <tt>using</tt> declarations and directives <em>are</em> used by the internal type system to track type-names. Therefore, if you have code like this: </p> @@ -5115,7 +5458,7 @@ exit # 'a' is released, SWIG unref 'a' called in the destructor wra <p> -<tt>using</tt> declarations are sometimes used to adjust access to members of +C++ <tt>using</tt> declarations are sometimes used to introduce members of base classes. For example: </p> @@ -5123,7 +5466,7 @@ base classes. For example: <pre> class Foo { public: - int blah(int x); + int blah(int x); }; class Bar { @@ -5171,7 +5514,13 @@ you wrap this code in Python, the module works just like you would expect: </div> <p> -<tt>using</tt> declarations can also be used to change access when applicable. For example: +The C++11 standard supports using declarations for inheriting constructors and this is covered in +<a href="CPlusPlus11_object_construction_improvement">Object construction improvement</a>. +</p> + +<p> +C++ <tt>using</tt> declarations can also be used to change access when applicable. +For example, protected methods in a base class can be made public in a derived class: </p> <div class="code"> @@ -5204,15 +5553,15 @@ ignored in a base class, it will also be ignored by a <tt>using</tt> declaration <p> Because a <tt>using</tt> declaration does not provide fine-grained -control over the declarations that get imported, it may be difficult +control over the declarations that get imported, because a single <tt>using</tt> declaration +may introduce multiple methods, it may be difficult to manage such declarations in applications that make heavy use of SWIG customization features. If you can't get <tt>using</tt> to work -correctly, you can always change the interface to the following: +correctly, you can always modify the C++ code to handle SWIG differently such as: </p> <div class="code"> <pre> - class FooBar : public Foo, public Bar { public: #ifndef SWIG @@ -5229,12 +5578,35 @@ public: </div> <p> +If the C++ code being wrapped cannot be changed, make judicious usage of <tt>%extend</tt> and <tt>%rename</tt> +to ignore and unignore declarations. The example below is effectively the same as above: +</p> + +<div class="code"> +<pre> +%extend FooBar { + int blah(int x) { return $self->Foo::blah(x); } + double blah(double x) { return $self->Bar::blah(x); } +} +%ignore FooBar::blah; // ignore all FooBar::blah below +%rename("") FooBar::blah(const char *x); // parameterized unignore + +class FooBar : public Foo, public Bar { +public: + using Foo::blah; + using Bar::blah; + char *blah(const char *x); +}; +</pre> +</div> + +<p> <b>Notes:</b> </p> <ul> -<li><p>If a derived class redefines a method defined in a base class, then a <tt>using</tt> declaration -won't cause a conflict. For example:</p> +<li><p>If a derived class introduces a method defined in a base class via a <tt>using</tt> declaration, +there won't be a conflict due to incorrect additional methods. For example:</p> <div class="code"> <pre> @@ -5246,14 +5618,14 @@ public: class Bar : public Foo { public: - using Foo::blah; // Only imports blah(double); + using Foo::blah; // Only introduces blah(double); int blah(int); }; </pre> </div> -<li><p>Resolving ambiguity in overloading may prevent declarations from being -imported by <tt>using</tt>. For example: +<li><p>Renaming methods may prevent methods from being +introduced into the derived class via <tt>using</tt> declarations. For example: </p> <div class="code"> @@ -5267,11 +5639,38 @@ public: class Bar : public Foo { public: - using Foo::blah; // Only imports blah(int) + using Foo::blah; // Only introduces blah(int) double blah(double x); }; </pre> </div> + +<p> +The problem here is <tt>Foo::blah</tt> is renamed to <tt>blah_long</tt> in the target language, but +the <tt>using</tt> declaration in Bar is not renamed in the target language and thinks all introduced methods should simply +be called <tt>blah</tt>. +It is not clear what target language names should be used in Bar and so the conflicting names are effectively ignored +as they are not introduced into the derived class for the target language wrappers. +In such situations SWIG will emit a warning: +</p> + +<div class="shell"> +<pre> +example.i:15: Warning 526: Using declaration Foo::blah, with name 'blah', is not actually using +example.i:10: Warning 526: the method from Foo::blah(long), with name 'blah_long', as the names are different. +</pre> +</div> + +<p> +<b>Compatibility Note:</b> +This warning message was introduced in SWIG-4.1.0. +Prior versions also effectively ignored the using declaration for the same reasons, but were silent about it. +</p> + +<p> +If methods really need different names, please use of combinations of <tt>%rename</tt>, <tt>%ignore</tt> and <tt>%extend</tt> to achieve the desired outcome. +</p> + </ul> <H2><a name="SWIGPlus_nested_classes">6.27 Nested classes</a></H2> |