diff options
Diffstat (limited to 'Doc/Manual/SWIGPlus.html')
| -rw-r--r-- | Doc/Manual/SWIGPlus.html | 1053 |
1 files changed, 703 insertions, 350 deletions
diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index 3e7860b9b..dc9ae0f7e 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -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,16 +38,27 @@ <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_overloaded_methods">Wrapping Overloaded Functions and Methods</a> +<li><a href="#SWIGPlus_default_args">Default arguments</a> +<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">Wrapping overloaded operators</a> +<li><a href="#SWIGPlus_nn28">Overloaded operators</a> <li><a href="#SWIGPlus_class_extension">Class extension</a> <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_specialization">Template specialization</a> +<li><a href="#SWIGPlus_template_member">Member templates</a> +<li><a href="#SWIGPlus_template_scoping">Scoping and templates</a> +<li><a href="#SWIGPlus_template_more">More on templates</a> +</ul> <li><a href="#SWIGPlus_namespaces">Namespaces</a> <ul> <li><a href="#SWIGPlus_nspace">The nspace feature for namespaces</a> @@ -62,6 +72,11 @@ <li><a href="#SWIGPlus_nn35">Using declarations and inheritance</a> <li><a href="#SWIGPlus_nested_classes">Nested classes</a> <li><a href="#SWIGPlus_const">A brief rant about const-correctness</a> +<li><a href="#SWIGPlus_target_language_callbacks">Callbacks to the target language</a> +<ul> +<li><a href="#SWIGPlus_director_classes_introduction">Introduction to director classes</a> +<li><a href="#SWIGPlus_directors_for_function_pointers">Using directors and target language callbacks</a> +</ul> <li><a href="#SWIGPlus_nn42">Where to go for more information</a> </ul> </div> @@ -70,9 +85,15 @@ <p> -This chapter describes SWIG's support for wrapping C++. As a prerequisite, +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. +As a prerequisite, you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see -how SWIG wraps ANSI C. Support for C++ builds upon ANSI C +how SWIG wraps ISO C. Support for C++ builds upon ISO C wrapping and that material will be useful in understanding this chapter. </p> @@ -123,7 +144,7 @@ yourself in the foot. You will just have to be careful. <p> To wrap C++, SWIG uses a layered approach to code generation. -At the lowest level, SWIG generates a collection of procedural ANSI-C style +At the lowest level, SWIG generates a collection of procedural ISO C style wrappers. These wrappers take care of basic type conversion, type checking, error handling, and other low-level details of the C++ binding. These wrappers are also sufficient to bind C++ into any target language @@ -346,8 +367,8 @@ public: class Spam { public: - Foo *value; - ... + Foo *value; + ... }; </pre> </div> @@ -706,7 +727,7 @@ class Foo { protected: Foo(); // Not wrapped. public: - ... + ... }; </pre> </div> @@ -726,7 +747,7 @@ public: class Grok : public Bar { public: - Grok(); // Not wrapped. No implementation of abstract spam(). + Grok(); // Not wrapped. No implementation of abstract spam(). }; </pre> </div> @@ -777,9 +798,9 @@ the normal constructor function. For example, if you have this: <pre> class List { public: - List(); - List(const List &); // Copy constructor - ... + List(); + List(const List &); // Copy constructor + ... }; </pre> </div> @@ -803,7 +824,7 @@ through a special function like this: <div class="code"> <pre> List *copy_List(List *f) { - return new List(*f); + return new List(*f); } </pre> </div> @@ -832,7 +853,7 @@ However, copy constructor wrappers can be generated if using the <tt>copyctor</t class List { public: - List(); + List(); }; </pre> </div> @@ -851,9 +872,9 @@ could be wrapped, but they had to be renamed. For example: <pre> class Foo { public: - Foo(); + Foo(); %name(CopyFoo) Foo(const Foo &); - ... + ... }; </pre> </div> @@ -969,8 +990,8 @@ not primitive types, such as classes. For instance, if you had another class lik <pre> class Foo { public: - List items; - ... + List items; + ... </pre> </div> @@ -982,10 +1003,10 @@ For example: <div class="code"> <pre> List *Foo_items_get(Foo *self) { - return &self->items; + return &self->items; } void Foo_items_set(Foo *self, List *value) { - self->items = *value; + self->items = *value; } </pre> </div> @@ -1007,10 +1028,10 @@ It is the naturalvar feature and can be used to effectively change the way acces <div class="code"> <pre> const List &Foo_items_get(Foo *self) { - return self->items; + return self->items; } void Foo_items_set(Foo *self, const List &value) { - self->items = value; + self->items = value; } </pre> </div> @@ -1094,113 +1115,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> @@ -1220,7 +1135,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> @@ -1250,7 +1165,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> @@ -1278,7 +1193,7 @@ equivalent to one generated for the following declaration <pre> class Foo { public: - ... + ... }; void blah(Foo *f); @@ -1311,7 +1226,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> @@ -1411,7 +1326,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> @@ -1485,8 +1400,8 @@ class A; %feature("valuewrapper") B; struct B { - B(); - // .... + B(); + // .... }; </pre></div> @@ -1515,7 +1430,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> @@ -1701,7 +1616,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> @@ -1833,7 +1748,113 @@ 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_overloaded_methods">6.15 Wrapping Overloaded Functions and Methods</a></H2> +<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 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> + +<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">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 +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 Overloaded functions and methods</a></H2> <p> @@ -2021,7 +2042,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> @@ -2139,7 +2160,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> @@ -2399,8 +2420,8 @@ the first renaming rule found on a depth-first traversal of the class hierarchy is used. </li> -<li><p>The name matching rules strictly follow member qualification rules. -For example, if you have a class like this:</p> +<li><p>The name matching rules strictly follow member qualifier rules. +For example, if you have a class and member with a member that is const qualified like this:</p> <div class="code"> <pre> @@ -2424,7 +2445,7 @@ the declaration </div> <p> -will not apply as there is no unqualified member <tt>bar()</tt>. The following will apply as +will not apply as there is no unqualified member <tt>bar()</tt>. The following will apply the rename as the qualifier matches correctly: </p> @@ -2435,6 +2456,26 @@ the qualifier matches correctly: </div> <p> +Similarly for combinations of cv-qualifiers and ref-qualifiers, all the qualifiers must be specified to match correctly: +</p> + +<div class="code"> +<pre> +%rename(name) Jam::bar(); // will not match +%rename(name) Jam::bar() &; // will not match +%rename(name) Jam::bar() const; // will not match +%rename(name) Jam::bar() const &; // ok, will match + +class Jam { +public: + ... + void bar() const &; + ... +}; +</pre> +</div> + +<p> An often overlooked C++ feature is that classes can define two different overloaded members that differ only in their qualifiers, like this: </p> @@ -2466,7 +2507,7 @@ For example we can give them separate names in the target language: <p> Similarly, if you merely wanted to ignore one of the declarations, use <tt>%ignore</tt> -with the full qualification. For example, the following directive +with the full qualifier. For example, the following directive would tell SWIG to ignore the <tt>const</tt> version of <tt>bar()</tt> above: </p> @@ -2532,8 +2573,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"> @@ -2543,8 +2583,23 @@ So if instead we have: </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> @@ -2586,7 +2641,7 @@ As a general rule, statically typed languages like Java are able to provide more than dynamically typed languages like Perl, Python, Ruby, and Tcl. </p> -<H2><a name="SWIGPlus_nn28">6.16 Wrapping overloaded operators</a></H2> +<H2><a name="SWIGPlus_nn28">6.16 Overloaded operators</a></H2> <p> @@ -2779,7 +2834,7 @@ into two methods such that additional logic can be packed into the operations; C <tt>this[type key] { get { ... } set { ... }}</tt>, Python uses <tt>__getitem__</tt> and <tt>__setitem__</tt>, etc. In C++ if the return type of <tt>operator[]</tt> is a reference and the method is const, it is often indicative of the <i>setter</i>, -and and the <i>getter</i> is usually a const function return an object by value. +and the <i>getter</i> is usually a const function return an object by value. In the absence of any hard and fast rules and the fact that there may be multiple index operators, it is up to the user to choose the getter and setter to use by using %rename as shown earlier. </p> @@ -2936,63 +2991,76 @@ as <tt>vector<int></tt>. The wrapper for <tt>foo()</tt> will accept either variant. </p> +<H3><a name="SWIGPlus_template_directive">6.18.1 The %template directive</a></H3> + + <p> -Starting with SWIG-1.3.7, simple C++ template declarations can also be -wrapped. SWIG-1.3.12 greatly expands upon the earlier implementation. Before discussing this any further, there are a few things -you need to know about template wrapping. First, a bare C++ template +There are a couple of important points about template wrapping. +First, a bare C++ template does not define any sort of runnable object-code for which SWIG can normally create a wrapper. Therefore, in order to wrap a template, you need to give SWIG information about a particular template -instantiation (e.g., <tt>vector<int></tt>, +instantiation (e.g., <tt>vector<int></tt>, <tt>array<double></tt>, etc.). Second, an instantiation name such as <tt>vector<int></tt> is generally not a valid identifier name in most target languages. Thus, you will need to give the -template instantiation a more suitable name such as <tt>intvector</tt> -when creating a wrapper. +template instantiation a more suitable name such as <tt>intvector</tt>. </p> <p> -To illustrate, consider the following template definition: +To illustrate, consider the following class template definition: </p> <div class="code"><pre> template<class T> class List { private: - T *data; - int nitems; - int maxitems; + T *data; + int nitems; + int maxitems; public: - List(int max) { - data = new T [max]; - nitems = 0; - maxitems = max; - } - ~List() { - delete [] data; - }; - void append(T obj) { - if (nitems < maxitems) { - data[nitems++] = obj; - } - } - int length() { - return nitems; - } - T get(int n) { - return data[n]; + List(int max) { + data = new T [max]; + nitems = 0; + maxitems = max; + } + ~List() { + delete [] data; + }; + void append(T obj) { + if (nitems < maxitems) { + data[nitems++] = obj; } + } + int length() { + return nitems; + } + T get(int n) { + return data[n]; + } }; </pre></div> <p> -By itself, this template declaration is useless--SWIG simply ignores it -because it doesn't know how to generate any code until unless a definition of +By itself, this class template is useless--SWIG simply ignores it +because it doesn't know how to generate any code unless a definition of <tt>T</tt> is provided. +The <tt>%template</tt> directive is required to instantiate the template for use in a target language. +The directive requires an identifier name for use in the target language plus the template for instantiation. +The example below instantiates <tt>List<int></tt> for use as a class named <tt>intList</tt>: </p> +<div class="code"> +<pre> +%template(intList) List<int>; +</pre> +</div> + <p> -One way to create wrappers for a specific template instantiation is to simply -provide an expanded version of the class directly like this: +The instantiation expands the template code as a C++ compiler would do and then makes it available +under the given identifier name. +Essentially it is the same as wrapping the following concept code where +the class template definition has <tt>T</TT> expanded to <tt>int</tt> +(note that this is not entirely valid syntax): </p> <div class="code"> @@ -3000,60 +3068,112 @@ provide an expanded version of the class directly like this: %rename(intList) List<int>; // Rename to a suitable identifier class List<int> { private: - int *data; - int nitems; - int maxitems; + int *data; + int nitems; + int maxitems; public: - List(int max); - ~List(); - void append(int obj); - int length(); - int get(int n); + List(int max); + ~List(); + void append(int obj); + int length(); + int get(int n); }; </pre> </div> <p> -The <tt>%rename</tt> directive is needed to give the template class an appropriate identifier -name in the target language (most languages would not recognize C++ template syntax as a valid -class name). The rest of the code is the same as what would appear in a normal -class definition. +The argument to <tt>%template()</tt> is the name of the instantiation +in the target language. The name you choose should not conflict with +any other declarations in the interface file with one exception---it +is okay for the template name to match that of a typedef declaration. +For example: +</p> + +<div class="code"> +<pre> +%template(intList) List<int>; +... +typedef List<int> intList; // OK +</pre> +</div> + +<p> +The <tt>%template</tt> directive +must always appear <em>after</em> the definition of the template to be expanded, so the following will work: </p> +<div class="code"> +<pre> +template<class T> class List { ... }; +%template(intList) List<int>; +</pre> +</div> + <p> -Since manual expansion of templates gets old in a hurry, the <tt>%template</tt> directive can -be used to create instantiations of a template class. Semantically, <tt>%template</tt> is -simply a shortcut---it expands template code in exactly the same way as shown above. Here -are some examples: +but if %template is used before the template definition, such as: </p> <div class="code"> <pre> -/* Instantiate a few different versions of the template */ %template(intList) List<int>; -%template(doubleList) List<double>; +template<class T> class List { ... }; </pre> </div> <p> -The argument to <tt>%template()</tt> is the name of the instantiation -in the target language. The name you choose should not conflict with -any other declarations in the interface file with one exception---it -is okay for the template name to match that of a typedef declaration. -For example: +SWIG will generate an error: +</p> + +<div class="shell"> +<pre> +example.i:3: Error: Template 'List' undefined. +</pre> +</div> + +<p> +Since the type system knows how to handle <tt>typedef</tt>, it is +generally not necessary to instantiate different versions of a template +for typenames that are equivalent. For instance, consider this code: </p> <div class="code"> <pre> %template(intList) List<int>; +typedef int Integer; ... -typedef List<int> intList; // OK +void foo(List<Integer> *x); </pre> </div> <p> -SWIG can also generate wrappers for function templates using a similar technique. +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). +</p> + +<p> +The template provided to <tt>%template</tt> for instantiation must be the actual template and not a typedef to a template. +</p> + +<div class="code"> +<pre> +typedef List<int> ListOfInt; + +%template(intList) List<int>; // ok +%template(intList) ListOfInt; // illegal - Syntax error +</pre> +</div> + + +<H3><a name="SWIGPlus_template_functions">6.18.2 Function templates</a></H3> + + +<p> +SWIG can also generate wrappers for function templates using a similar technique +to that shown above for class templates. For example: </p> @@ -3074,6 +3194,28 @@ instantiations of the function. </p> <p> +SWIG even supports overloaded templated functions. As usual the <tt>%template</tt> directive +is used to wrap templated functions. For example: +</p> + +<div class="code"> +<pre> +template<class T> void foo(T x) { }; +template<class T> void foo(T x, T y) { }; + +%template(foo) foo<int>; +</pre> +</div> + +<p> +This will generate two overloaded wrapper methods, the first will take a single integer as an argument +and the second will take two integer arguments. +</p> + +<H3><a name="SWIGPlus_template_classes">6.18.3 Default template arguments</a></H3> + + +<p> The number of arguments supplied to <tt>%template</tt> should match that in the original template definition. Template default arguments are supported. For example: </p> @@ -3110,28 +3252,8 @@ instantiation only once in order to reduce the potential for code bloat. </p> -<p> -Since the type system knows how to handle <tt>typedef</tt>, it is -generally not necessary to instantiate different versions of a template -for typenames that are equivalent. For instance, consider this code: -</p> +<H3><a name="SWIGPlus_template_class_inheritance">6.18.4 Template base classes</a></H3> -<div class="code"> -<pre> -%template(intList) vector<int>; -typedef int Integer; -... -void foo(vector<Integer> *x); -</pre> -</div> - -<p> -In this case, <tt>vector<Integer></tt> is exactly the same type as -<tt>vector<int></tt>. Any use of <tt>Vector<Integer></tt> is mapped back to the -instantiation of <tt>vector<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). -</p> <p> When a template is instantiated using <tt>%template</tt>, information @@ -3158,13 +3280,13 @@ nothing is known about <tt>List<int></tt>, you will get a warning message <div class="shell"> <pre> -example.h:42: Warning 401. Nothing known about class 'List<int >'. Ignored. -example.h:42: Warning 401. Maybe you forgot to instantiate 'List<int >' using %template. +example.h:42: Warning 401. Nothing known about class 'List< int >'. Ignored. +example.h:42: Warning 401. Maybe you forgot to instantiate 'List< int >' using %template. </pre> </div> <p> -If a template class inherits from another template class, you need to +If a class template inherits from another class template, you need to make sure that base classes are instantiated before derived classes. For example: </p> @@ -3235,6 +3357,9 @@ 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> + + <p> The SWIG template mechanism <em>does</em> support specialization. For instance, if you define a class like this, @@ -3244,15 +3369,15 @@ a class like this, <pre> template<> class List<int> { private: - int *data; - int nitems; - int maxitems; + int *data; + int nitems; + int maxitems; public: - List(int max); - ~List(); - void append(int obj); - int length(); - int get(int n); + List(int max); + ~List(); + void append(int obj); + int length(); + int get(int n); }; </pre> </div> @@ -3275,15 +3400,15 @@ code defines a template that is applied when the template argument is a pointer. <pre> template<class T> class List<T*> { private: - T *data; - int nitems; - int maxitems; + T *data; + int nitems; + int maxitems; public: - List(int max); - ~List(); - void append(int obj); - int length(); - T get(int n); + List(int max); + ~List(); + void append(T obj); + int length(); + T get(int n); }; </pre> </div> @@ -3322,10 +3447,13 @@ 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> + + <p> -Member function templates are supported. The underlying principle is the same +Member templates are supported. The underlying principle is the same as for normal templates--SWIG can't create a wrapper unless you provide -more information about types. For example, a class with a member template might +more information about types. For example, a class with a member function template might look like this: </p> @@ -3400,11 +3528,6 @@ methods to the Foo class. <p> -Note: because of the way that templates are handled, the <tt>%template</tt> directive -must always appear <em>after</em> the definition of the template to be expanded. -</p> - -<p> Now, if your target language supports overloading, you can even try </p> @@ -3424,7 +3547,7 @@ depending on the argument type. <p> When used with members, the <tt>%template</tt> directive may be placed in another -template class. Here is a slightly perverse example: +class template. Here is a slightly perverse example: </p> <div class="code"> @@ -3475,7 +3598,7 @@ template<class T1, class T2> struct pair { <p> This declaration is perfectly acceptable to SWIG, but the constructor template will be ignored unless you explicitly expand it. To do that, you could expand a few versions of the constructor -in the template class itself. For example: +in the class template itself. For example: </p> <div class="code"> @@ -3536,6 +3659,110 @@ 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> + + +<p> +The <tt>%template</tt> directive for a class template is the equivalent to an explicit instantiation +of a C++ class template. The scope for a valid <tt>%template</tt> instantiation is the same +as the scope required for a valid explicit instantiation of a C++ template. +A definition of the template for the explicit instantiation must be in scope +where the instantiation is declared and must not be enclosed within a different namespace. +</p> + +<p> +For example, a few <tt>%template</tt> instantiations and C++ explicit instantiations are shown below: +</p> + +<div class="code"> +<pre> +namespace N { + template<typename T> class C {}; +} + +// valid +%template(cin) N::C<int>; +template class N::C<int>; + +// valid +namespace N { + %template(cin) C<int>; + template class C<int>; +} + +// valid +using namespace N; +%template(cin) C<int>; +template class C<int>; + +// valid +using N::C; +%template(cin) C<int>; +template class C<int>; + +// ill-formed +namespace unrelated { + using N::C; + %template(cin) C<int>; + template class C<int>; +} + +// ill-formed +namespace unrelated { + using namespace N; + %template(cin) C<int>; + template class C<int>; +} + +// ill-formed +namespace unrelated { + namespace N { + %template(cin) C<int>; + template class C<int>; + } +} + +// ill-formed +namespace unrelated { + %template(cin) N::C<int>; + template class N::C<int>; +} +</pre> +</div> + +<p> +When the scope is incorrect, such as for the ill-formed examples above, an error occurs: +</p> + +<div class="shell"> +<pre> +cpp_template_scope.i:34: Error: 'C' resolves to 'N::C' and was incorrectly instantiated +in scope 'unrelated' instead of within scope 'N'. +</pre> +</div> + +<p> +A note for the C++ standard geeks out there; a valid instantiation is one which conforms to +the C++03 standard as C++11 made a change to disallow using declarations and using directives to find a template. +</p> + +<div class="code"> +<pre> +// valid C++03, ill-formed C++11 +using N::C; +template class C<int>; +</pre> +</div> + +<p> +<b>Compatibility Note</b>: Versions prior to SWIG-4.0.0 did not error out with incorrectly scoped +<tt>%template</tt> declarations, but this led to numerous subtle template scope problems. +</p> + + +<H3><a name="SWIGPlus_template_more">6.18.8 More on templates</a></H3> + + <p> If all of this isn't quite enough and you really want to make someone's head explode, SWIG directives such as @@ -3568,7 +3795,7 @@ instantiation. </p> <p> -It is also possible to separate these declarations from the template class. For example: +It is also possible to separate these declarations from the class template. For example: </p> <div class="code"> @@ -3587,11 +3814,11 @@ It is also possible to separate these declarations from the template class. For ... template<class T> class List { - ... - public: - List() { } - T get(int index); - ... + ... + public: + List() { } + T get(int index); + ... }; </pre> </div> @@ -3609,33 +3836,14 @@ additional methods to a specific instantiation. For example: %template(intList) List<int>; %extend List<int> { - void blah() { - printf("Hey, I'm an List<int>!\n"); - } + void blah() { + printf("Hey, I'm an List<int>!\n"); + } }; </pre> </div> <p> -SWIG even supports overloaded templated functions. As usual the <tt>%template</tt> directive -is used to wrap templated functions. For example: -</p> - -<div class="code"> -<pre> -template<class T> void foo(T x) { }; -template<class T> void foo(T x, T y) { }; - -%template(foo) foo<int>; -</pre> -</div> - -<p> -This will generate two overloaded wrapper methods, the first will take a single integer as an argument -and the second will take two integer arguments. -</p> - -<p> It is even possible to extend a class via <tt>%extend</tt> with template methods, for example: </p> @@ -3694,20 +3902,20 @@ For example: <pre> template <class T> class OuterTemplateClass {}; -// The nested class OuterClass::InnerClass inherits from the template class +// The nested class OuterClass::InnerClass inherits from the class template // OuterTemplateClass<OuterClass::InnerStruct> and thus the template needs // to be expanded with %template before the OuterClass declaration. %template(OuterTemplateClass_OuterClass__InnerStruct) - OuterTemplateClass<OuterClass::InnerStruct> + OuterTemplateClass<OuterClass::InnerStruct> // Don't forget to use %feature("flatnested") for OuterClass::InnerStruct and // OuterClass::InnerClass if the target language doesn't support nested classes. class OuterClass { - public: - // Forward declarations: - struct InnerStruct; - class InnerClass; + public: + // Forward declarations: + struct InnerStruct; + class InnerClass; }; struct OuterClass::InnerStruct {}; @@ -3736,7 +3944,7 @@ introduced a new class name. This name could then be used with other directives <pre> %template(vectori) vector<int>; %extend vectori { - void somemethod() { } + void somemethod() { } }; </pre> </div> @@ -3750,7 +3958,7 @@ as the class name. For example: <pre> %template(vectori) vector<int>; %extend vector<int> { - void somemethod() { } + void somemethod() { } }; </pre> </div> @@ -3915,6 +4123,8 @@ then SWIG simply creates three wrapper functions <tt>bar()</tt>, <tt>spam()</tt>, and <tt>blah()</tt> in the target language. SWIG does not prepend the names with a namespace prefix nor are the functions packaged in any kind of nested scope. +Note that the default handling of flattening all the namespace scopes in the target language +can be changed via the <a href="#SWIGPlus_nspace">nspace feature</a>. </p> <p> @@ -4009,7 +4219,7 @@ in a different namespace. For example: <div class="code"> <pre> namespace foo { - template<typename T> T max(T a, T b) { return a > b ? a : b; } + template<typename T> T max(T a, T b) { return a > b ? a : b; } } using foo::max; @@ -4018,8 +4228,8 @@ using foo::max; %template(maxfloat) foo::max<float>; // Okay (qualified name). namespace bar { - using namespace foo; - %template(maxdouble) max<double>; // Okay. + using namespace foo; + %template(maxdouble) max<double>; // Okay. } </pre> </div> @@ -4040,7 +4250,7 @@ namespace foo { typedef int Integer; class bar { public: - ... + ... }; } @@ -4203,9 +4413,7 @@ namespace foo { <p> <b>Note:</b> The flattening of namespaces is only intended to serve as a basic namespace implementation. -None of the target language modules are currently programmed -with any namespace awareness. In the future, language modules may or may not provide -more advanced namespace support. +More advanced handling of namespaces is discussed next. </p> <H3><a name="SWIGPlus_nspace">6.19.1 The nspace feature for namespaces</a></H3> @@ -4301,9 +4509,9 @@ In the example below, the generic template type is used to rename to <tt>bbb</tt <div class="code"> <pre> -%rename(bbb) Space::ABC::aaa(T t); // will match but with lower precedence than ccc +%rename(bbb) Space::ABC::aaa(T t); // will match but with lower precedence than ccc %rename(ccc) Space::ABC<Space::XYZ>::aaa(Space::XYZ t);// will match but with higher precedence - // than bbb + // than bbb namespace Space { class XYZ {}; @@ -4381,9 +4589,9 @@ class Error { }; class Foo { public: - ... - void blah() throw(Error); - ... + ... + void blah() throw(Error); + ... }; </pre> </div> @@ -4408,7 +4616,7 @@ except Error, e: <p> Details of how to tailor code for handling the caught C++ exception and converting it into the target language's exception/error handling mechanism -is outlined in the <a href="Typemaps.html#throws_typemap">"throws" typemap</a> section. +is outlined in the <a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemap</a> section. </p> <p> @@ -4425,7 +4633,7 @@ The next section details a way of simulating an exception specification or repla Exceptions are automatically handled for methods with an exception specification. Similar handling can be achieved for methods without exception specifications through the <tt>%catches</tt> feature. It is also possible to replace any declared exception specification using the <tt>%catches</tt> feature. -In fact, <tt>%catches</tt> uses the same <a href="Typemaps.html#throws_typemap">"throws" typemaps</a> that SWIG uses for exception specifications in handling exceptions. +In fact, <tt>%catches</tt> uses the same <a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemaps</a> that SWIG uses for exception specifications in handling exceptions. The <tt>%catches</tt> feature must contain a list of possible types that can be thrown. For each type that is in the list, SWIG will generate a catch handler, in the same way that it would for types declared in the exception specification. Note that the list can also include the catch all specification "...". @@ -4445,10 +4653,10 @@ struct Error4 : EBase { }; class Foo { public: - ... - void bar(); - void blah() throw(Error1, Error2, Error3, Error4); - ... + ... + void bar(); + void blah() throw(Error1, Error2, Error3, Error4); + ... }; </pre> </div> @@ -4524,7 +4732,7 @@ for member pointers. <p> In some C++ programs, objects are often encapsulated by smart-pointers or proxy classes. This is sometimes done to implement automatic memory management (reference counting) or -persistence. Typically a smart-pointer is defined by a template class where +persistence. Typically a smart-pointer is defined by a class template where the <tt>-></tt> operator has been overloaded. This class is then wrapped around some other class. For example: </p> @@ -4533,21 +4741,21 @@ around some other class. For example: <pre> // Smart-pointer class template<class T> class SmartPtr { - T *pointee; + T *pointee; public: - SmartPtr(T *p) : pointee(p) { ... } - T *operator->() { - return pointee; - } - ... + SmartPtr(T *p) : pointee(p) { ... } + T *operator->() { + return pointee; + } + ... }; // Ordinary class class Foo_Impl { public: - int x; - virtual void bar(); - ... + int x; + virtual void bar(); + ... }; // Smart-pointer wrapper @@ -4555,13 +4763,13 @@ typedef SmartPtr<Foo_Impl> Foo; // Create smart pointer Foo Foo make_Foo() { - return SmartPtr<Foo_Impl>(new Foo_Impl()); + return SmartPtr<Foo_Impl>(new Foo_Impl()); } // Do something with smart pointer Foo void do_something(Foo f) { - printf("x = %d\n", f->x); - f->bar(); + printf("x = %d\n", f->x); + f->bar(); } // Call the wrapped smart pointer proxy class in the target language 'Foo' @@ -4660,13 +4868,13 @@ example, if you have this code</p> <pre> class Foo { public: - int x; + int x; }; class Bar { public: - int x; - Foo *operator->(); + int x; + Foo *operator->(); }; </pre> </div> @@ -4829,19 +5037,19 @@ For example: <p> where the code passed to the "ref" and "unref" features will be -executed as needed whenever a new object is passed to python, or when -python tries to release the proxy object instance, respectively. +executed as needed whenever a new object is passed to Python, or when +Python tries to release the proxy object instance, respectively. </p> <p> -On the python side, the use of a reference counted object is no +On the Python side, the use of a reference counted object is no different to any other regular instance: </p> <div class="targetlang"> <pre> def create_A(): - a = A() # SWIG ref 'a' - new object is passed to python (count: 1) + a = A() # SWIG ref 'a' - new object is passed to Python (count: 1) b1 = B(a) # C++ ref 'a (count: 2) if 1 + 1 == 2: b2 = B(a) # C++ ref 'a' (count: 3) @@ -4869,8 +5077,8 @@ features: <p> In other words, SWIG will not do anything special when a new object -is passed to python, and it will always 'delete' the underlying object when -python releases the proxy instance. +is passed to Python, and it will always 'delete' the underlying object when +Python releases the proxy instance. </p> <p> @@ -4915,19 +5123,19 @@ base classes. For example: <pre> class Foo { public: - int blah(int x); + int blah(int x); }; class Bar { public: - double blah(double x); + double blah(double x); }; class FooBar : public Foo, public Bar { public: - using Foo::blah; - using Bar::blah; - char *blah(const char *x); + using Foo::blah; + using Bar::blah; + char *blah(const char *x); }; </pre> </div> @@ -4970,14 +5178,14 @@ you wrap this code in Python, the module works just like you would expect: <pre> class Foo { protected: - int x; - int blah(int x); + int x; + int blah(int x); }; class Bar : public Foo { public: - using Foo::x; // Make x public - using Foo::blah; // Make blah public + using Foo::x; // Make x public + using Foo::blah; // Make blah public }; </pre> </div> @@ -5008,14 +5216,14 @@ correctly, you can always change the interface to the following: class FooBar : public Foo, public Bar { public: #ifndef SWIG - using Foo::blah; - using Bar::blah; + using Foo::blah; + using Bar::blah; #else - int blah(int x); // explicitly tell SWIG about other declarations - double blah(double x); + int blah(int x); // explicitly tell SWIG about other declarations + double blah(double x); #endif - char *blah(const char *x); + char *blah(const char *x); }; </pre> </div> @@ -5077,7 +5285,7 @@ normal classes. </p> <p> If the target language doesn't support nested classes directly, or the support is not implemented in the -language module (like for python currently), then the visible nested classes are moved to the same name +language module (like for Python currently), then the visible nested classes are moved to the same name space as the containing class (nesting hierarchy is "flattened"). The same behaviour may be turned on for C# and Java by the %feature ("flatnested"); If there is a class with the same name in the outer namespace the inner class (or the global one) may be renamed or ignored: @@ -5188,7 +5396,152 @@ using another tool if maintaining constness is the most important part of your project. </p> -<H2><a name="SWIGPlus_nn42">6.29 Where to go for more information</a></H2> +<H2><a name="SWIGPlus_target_language_callbacks">6.29 Callbacks to the target language</a></H2> + + +<p> +C/C++ function pointers are often used for callbacks and this is discussed in the +<a href="SWIG.html#SWIG_nn30">Pointers to functions and callbacks</a> section. +The callback techniques described therein provide a way to control callbacks to a C/C++ function but not callbacks into the target language. +The techniques described below show how the director feature can be used to support callbacks from C/C++ to the target language. +</p> + +<H3><a name="SWIGPlus_director_classes_introduction">6.29.1 Introduction to director classes</a></H3> + + +<p> +The director feature enables the ability for a target language class to derive from a wrapped C++ class. +The target language can override virtual methods of a wrapped C++ class, thereby supporting cross-language polymorphism. +Code can 'call up' from C++ into the target language by simply calling a virtual method overridden in a derived class in the target language. +The wrapped C++ classes that have this ability are termed 'director' classes. +The director feature is documented individually in each target language and the reader should locate and read this to obtain a full understanding of directors. +</p> + +<H3><a name="SWIGPlus_directors_for_function_pointers">6.29.2 Using directors and target language callbacks</a></H3> + + +<p> +SWIG's primary goal is to make it possible to call C/C++ code from a target language, however, the director feature enables the reverse. +While there isn't simple direct support for calling target language code from C, the director feature makes this possible. +It does require some work and additional wrapper code to be provided by the user. +The additional code required must be C++ and not C code and hence may introduce a small dependency on C++ if using a pure C project. +In a nutshell, the user must create a C++ base class and turn it into a director class. +A virtual method in the director base class is required. +SWIG generates the code to call up into the target language when wrapping the director virtual method. +</p> + +<p> +Let's look at some details next. +Consider the same function pointer for a callback called <tt>binary_op</tt> from the +<a href="SWIG.html#SWIG_nn30">Pointers to functions and callbacks</a> section. +For completeness, the code required for the module and director feature is also shown: +</p> + +<div class="code"><pre> +%module(directors="1") example + +%{ +int binary_op(int a, int b, int (*op)(int, int)) { + return op(a, b); +} +%} +</pre></div> + +<p> +The goal is to have a target language function that gets called by <tt>binary_op</tt>. +The target language function should have the equivalent signature as the C/C++ function pointer <tt>int (*op)(int, int)</tt>. +As we are using directors, we need a C++ virtual method with this signature, so let's +define the C++ class and pure virtual method first and make it a director class via the +director feature: +</p> + +<div class="code"><pre> +%feature("director") BinaryOp; + +%inline %{ +struct BinaryOp { + virtual int handle(int a, int b) = 0; + virtual ~BinaryOp() {} +}; +%} +</pre></div> + +<p> +The following <tt>handler_helper</tt> function and <tt>binary_op_wrapper</tt> function completes the code needed in the +C++/SWIG layer. The <tt>binary_op_wrapper</tt> function is wrapped by SWIG and is very similar to the <tt>binary_op</tt> function, +however, it takes a pointer to the director base class <tt>BinaryOp</tt> instead of a C/C++ function pointer. +</p> + +<div class="code"><pre> +%{ +static BinaryOp *handler_ptr = NULL; +static int handler_helper(int a, int b) { + // Make the call up to the target language when handler_ptr + // is an instance of a target language director class + return handler_ptr->handle(a, b); +} +// If desired, handler_ptr above could be changed to a thread-local variable in order to make thread-safe +%} + +%inline %{ +int binary_op_wrapper(int a, int b, BinaryOp *handler) { + handler_ptr = handler; + int result = binary_op(a, b, &handler_helper); + handler = NULL; + return result; +} +%} +</pre></div> + +<p> +On the target language side, we need to derive a class from <tt>BinaryOp</tt> and override the +<tt>handle</tt> method. In Python this could be as simple as: +</p> + +<div class="targetlang"> +<pre> +import example + +# PythonBinaryOp class is defined and derived from C++ class BinaryOp +class PythonBinaryOp(example.BinaryOp): + + # Define Python class 'constructor' + def __init__(self): + # Call C++ base class constructor + example.BinaryOp.__init__(self) + + # Override C++ method: virtual int handle(int a, int b) = 0; + def handle(self, a, b): + # Return the product + return a * b +</pre> +</div> + +<p> +For this to work from Python, an instance of the <tt>PythonBinaryOp</tt> class is created +and then passed to <tt>binary_op_wrapper</tt>. The net result is the <tt>binary_op</tt> +function will in turn be called which will call <tt>handler_helper</tt> which will call +the virtual <tt>handle</tt> method, that is, the Python method <tt>handle</tt> in the PythonBinaryOp class. The result will be the product of 10 and 20 and make its way back to Python and hence +200 will be printed with the following code: +</p> + +<div class="targetlang"> +<pre> +handler = PythonBinaryOp() +result = example.binary_op_wrapper(10, 20, handler) +print result +</pre> +</div> + +<p> +This has thus demonstrated a C/C++ function pointer calling back into a target language function. +The code could be made a little more user friendly by using <tt>%rename</tt> to provide the +original <tt>binary_op</tt> name from the target language instead of <tt>binary_op_wrapper</tt>. +A C++ functor base class and Python functor class +could also be used instead, but these are left as exercises for the reader. +</p> + +<H2><a name="SWIGPlus_nn42">6.30 Where to go for more information</a></H2> <p> |