mirror of https://github.com/swig/swig
6209 lines
172 KiB
HTML
6209 lines
172 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>SWIG and C++</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<H1><a name="SWIGPlus">6 SWIG and C++</a></H1>
|
|
<!-- INDEX -->
|
|
<div class="sectiontoc">
|
|
<ul>
|
|
<li><a href="#SWIGPlus_nn2">Comments on C++ Wrapping</a>
|
|
<li><a href="#SWIGPlus_nn3">Approach</a>
|
|
<li><a href="#SWIGPlus_nn4">Supported C++ features</a>
|
|
<li><a href="#SWIGPlus_nn5">Command line options and compilation</a>
|
|
<li><a href="#SWIGPlus_nn38">Proxy classes</a>
|
|
<ul>
|
|
<li><a href="#SWIGPlus_nn39">Construction of proxy classes</a>
|
|
<li><a href="#SWIGPlus_nn40">Resource management in proxies</a>
|
|
<li><a href="#SWIGPlus_nn41">Language specific details</a>
|
|
</ul>
|
|
<li><a href="#SWIGPlus_nn6">Simple C++ wrapping</a>
|
|
<ul>
|
|
<li><a href="#SWIGPlus_nn7">Constructors and destructors</a>
|
|
<li><a href="#SWIGPlus_nn8">Default constructors, copy constructors and implicit destructors</a>
|
|
<li><a href="#SWIGPlus_nn9">When constructor wrappers aren't created</a>
|
|
<li><a href="#SWIGPlus_nn10">Copy constructors</a>
|
|
<li><a href="#SWIGPlus_nn11">Member functions</a>
|
|
<li><a href="#SWIGPlus_nn12">Static members</a>
|
|
<li><a href="#SWIGPlus_member_data">Member data</a>
|
|
</ul>
|
|
<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>
|
|
<li><a href="#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a>
|
|
<li><a href="#SWIGPlus_default_args">Default arguments</a>
|
|
<li><a href="#SWIGPlus_overloaded_methods">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">Renaming and ambiguity resolution</a>
|
|
<li><a href="#SWIGPlus_nn27">Comments on overloading</a>
|
|
</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>
|
|
<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>
|
|
<ul>
|
|
<li><a href="#SWIGPlus_nspace_feature_flag">%nspace for mirroring namespace hierarchies</a>
|
|
<li><a href="#SWIGPlus_nspacemove">%nspacemove for modifying namespace hierarchies</a>
|
|
<li><a href="#SWIGPlus_nspace_more">More about the nspace feature</a>
|
|
</ul>
|
|
</ul>
|
|
<li><a href="#SWIGPlus_renaming_templated_types_namespaces">Renaming templated types in namespaces</a>
|
|
<li><a href="#SWIGPlus_exception_specifications">Exception specifications</a>
|
|
<li><a href="#SWIGPlus_catches">Exception handling with %catches</a>
|
|
<li><a href="#SWIGPlus_nn33">Pointers to Members</a>
|
|
<li><a href="#SWIGPlus_smart_pointers">Smart pointers and operator->()</a>
|
|
<li><a href="#SWIGPlus_ref_unref">C++ reference counted objects - ref/unref feature</a>
|
|
<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>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
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>,
|
|
<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
|
|
wrapping and that material will be useful in understanding this chapter.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn2">6.1 Comments on C++ Wrapping</a></H2>
|
|
|
|
|
|
<p>
|
|
Because of its complexity and the fact that C++ can be
|
|
difficult to integrate with itself let alone other languages, SWIG
|
|
only provides support for a subset of C++ features. Fortunately,
|
|
this is now a rather large subset.
|
|
</p>
|
|
|
|
<p>
|
|
In part, the problem with C++ wrapping is that there is no
|
|
semantically obvious (or automatic ) way to map many of its advanced
|
|
features into other languages. As a simple example, consider the
|
|
problem of wrapping C++ multiple inheritance to a target language with
|
|
no such support. Similarly, the use of overloaded operators and
|
|
overloaded functions can be problematic when no such capability exists
|
|
in a target language.
|
|
</p>
|
|
|
|
<p>
|
|
A more subtle issue with C++ has to do with the way that some C++
|
|
programmers think about programming libraries. In the world of SWIG,
|
|
you are really trying to create binary-level software components for
|
|
use in other languages. In order for this to work, a "component" has
|
|
to contain real executable instructions and there has to be some kind
|
|
of binary linking mechanism for accessing its functionality. In
|
|
contrast, C++ has increasingly relied upon generic programming and
|
|
templates for much of its functionality.
|
|
Although templates are a powerful feature, they are largely orthogonal
|
|
to the whole notion of binary components and libraries. For example,
|
|
an STL <tt>vector</tt> does not define any kind of binary object for
|
|
which SWIG can just create a wrapper. To further complicate matters,
|
|
these libraries often utilize a lot of behind the scenes magic in
|
|
which the semantics of seemingly basic operations (e.g., pointer
|
|
dereferencing, procedure call, etc.) can be changed in dramatic and
|
|
sometimes non-obvious ways. Although this "magic" may present few
|
|
problems in a C++-only universe, it greatly complicates the problem of
|
|
crossing language boundaries and provides many opportunities to shoot
|
|
yourself in the foot. You will just have to be careful.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn3">6.2 Approach</a></H2>
|
|
|
|
|
|
<p>
|
|
To wrap C++, SWIG uses a layered approach to code generation.
|
|
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
|
|
that supports built-in procedures. In some sense, you might view this
|
|
layer of wrapping as providing a C library interface to C++.
|
|
On top of the low-level procedural (flattened) interface, SWIG generates proxy classes
|
|
that provide a natural object-oriented (OO) interface to the underlying code. The proxy classes are typically
|
|
written in the target language itself. For instance, in Python, a real
|
|
Python class is used to provide a wrapper around the underlying C++ object.
|
|
</p>
|
|
|
|
<p>
|
|
It is important to emphasize that SWIG takes a deliberately
|
|
conservative and non-intrusive approach to C++ wrapping. SWIG does not
|
|
encapsulate C++ classes inside a special C++ adaptor, it does not rely
|
|
upon templates, nor does it add in additional C++ inheritance when
|
|
generating wrappers. The last thing that most C++ programs need is
|
|
even more compiler magic. Therefore, SWIG tries to maintain a very
|
|
strict and clean separation between the implementation of your C++
|
|
application and the resulting wrapper code. You might say that SWIG
|
|
has been written to follow the principle of least surprise--it does
|
|
not play sneaky tricks with the C++ type system, it doesn't mess with
|
|
your class hierarchies, and it doesn't introduce new semantics.
|
|
Although this approach might not provide the most seamless integration
|
|
with C++, it is safe, simple, portable, and debuggable.
|
|
</p>
|
|
|
|
<p>
|
|
This approach results in generated code that uses just the most basic of C and C++ features,
|
|
no matter how complex the input C++ is.
|
|
SWIG will not force a newer standard of C++ to be required as the generated code complies
|
|
with ISO standard C++98.
|
|
However, there are a few features in later C++ standards that can be advantageous to use.
|
|
For example, C++11 move semantics are available to provide performance improvements.
|
|
So in some instances, SWIG will use features from newer C++ standards provided they are available.
|
|
This is made possible via the <tt>__cplusplus</tt> macro,
|
|
which is set by the C++ compiler to an appropriate standards defined value.
|
|
This means that if your compiler is configured to support say the C++11 standard, then there
|
|
may be some C++11 benefits available in the generated code, such as C++11 move semantics.
|
|
</p>
|
|
|
|
<p>
|
|
Some of this chapter focuses on the low-level procedural interface to
|
|
C++ that is used as the foundation for all language modules. Keep in
|
|
mind that the target languages also provide the high-level OO interface via
|
|
proxy classes. More detailed coverage can be found in the documentation
|
|
for each target language.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn4">6.3 Supported C++ features</a></H2>
|
|
|
|
|
|
<p>
|
|
SWIG currently supports most C++ features including the following:</p>
|
|
|
|
<ul>
|
|
<li>Classes
|
|
<li>Constructors and destructors
|
|
<li>Virtual functions
|
|
<li>Public inheritance (including multiple inheritance)
|
|
<li>Static functions
|
|
<li>Function and method overloading
|
|
<li>Operator overloading for many standard operators
|
|
<li>References
|
|
<li>Templates (including specialization and member templates)
|
|
<li>Pointers to members
|
|
<li>Namespaces
|
|
<li>Default parameters
|
|
<li>Smart pointers
|
|
</ul>
|
|
|
|
<p>
|
|
The following C++ features are not currently supported:</p>
|
|
|
|
<ul>
|
|
<li>Overloaded versions of certain operators (new, delete, etc.)
|
|
</ul>
|
|
|
|
<p>
|
|
As a rule of thumb, SWIG should not be used on raw C++ source files, use header files only.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG's C++ support is an ongoing project so some of these limitations may be lifted
|
|
in future releases. However, we make no promises. Also, submitting a bug report is a very
|
|
good way to get problems fixed (wink).
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn5">6.4 Command line options and compilation</a></H2>
|
|
|
|
|
|
<p>
|
|
When wrapping C++ code, it is critical that SWIG be called with the
|
|
`<tt>-c++</tt>' option. This changes the way a number of critical
|
|
features such as memory management are handled. It
|
|
also enables the recognition of C++ keywords. Without the <tt>-c++</tt>
|
|
flag, SWIG will either issue a warning or a large number of syntax
|
|
errors if it encounters C++ code in an interface file.</p>
|
|
|
|
<p>
|
|
When compiling and linking the resulting wrapper file, it is normal
|
|
to use the C++ compiler. For example:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
$ swig -c++ -tcl example.i
|
|
$ c++ -fPIC -c example_wrap.cxx
|
|
$ c++ example_wrap.o $(OBJS) -o example.so
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Unfortunately, the process varies slightly on each platform. Make sure
|
|
you refer to the documentation on each target language for further
|
|
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 some target languages and will generate just this
|
|
interface as in earlier versions.
|
|
|
|
<H2><a name="SWIGPlus_nn38">6.5 Proxy classes</a></H2>
|
|
|
|
|
|
<p>
|
|
In order to provide a natural mapping from C++ classes to the target language classes, SWIG's target
|
|
languages mostly wrap C++ classes with special proxy classes. These
|
|
proxy classes are typically implemented in the target language itself.
|
|
For example, if you're building a Python module, each C++ class is
|
|
wrapped by a Python proxy class. Or if you're building a Java module, each
|
|
C++ class is wrapped by a Java proxy class.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nn39">6.5.1 Construction of proxy classes</a></H3>
|
|
|
|
|
|
<p>
|
|
Proxy classes are always constructed as an extra layer of wrapping that uses low-level
|
|
accessor functions. To illustrate, suppose you had a
|
|
C++ class like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
Foo();
|
|
~Foo();
|
|
int bar(int x);
|
|
int x;
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Using C++ as pseudocode, a proxy class looks something like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class FooProxy {
|
|
private:
|
|
Foo *self;
|
|
public:
|
|
FooProxy() {
|
|
self = new_Foo();
|
|
}
|
|
~FooProxy() {
|
|
delete_Foo(self);
|
|
}
|
|
int bar(int x) {
|
|
return Foo_bar(self, x);
|
|
}
|
|
int x_get() {
|
|
return Foo_x_get(self);
|
|
}
|
|
void x_set(int x) {
|
|
Foo_x_set(self, x);
|
|
}
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Of course, always keep in mind that the real proxy class is written in the target language.
|
|
For example, in Python, the proxy might look roughly like this:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
class Foo:
|
|
def __init__(self):
|
|
self.this = new_Foo()
|
|
def __del__(self):
|
|
delete_Foo(self.this)
|
|
def bar(self, x):
|
|
return Foo_bar(self.this, x)
|
|
def __getattr__(self, name):
|
|
if name == 'x':
|
|
return Foo_x_get(self.this)
|
|
...
|
|
def __setattr__(self, name, value):
|
|
if name == 'x':
|
|
Foo_x_set(self.this, value)
|
|
...
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Again, it's important to emphasize that the low-level accessor functions are always used by the
|
|
proxy classes.
|
|
Whenever possible, proxies try to take advantage of language features that are similar to C++. This
|
|
might include operator overloading, exception handling, and other features.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nn40">6.5.2 Resource management in proxies</a></H3>
|
|
|
|
|
|
<p>
|
|
A major issue with proxies concerns the memory management of wrapped objects. Consider the following
|
|
C++ code:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
Foo();
|
|
~Foo();
|
|
int bar(int x);
|
|
int x;
|
|
};
|
|
|
|
class Spam {
|
|
public:
|
|
Foo *value;
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Consider some script code that uses these classes:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
f = Foo() # Creates a new Foo
|
|
s = Spam() # Creates a new Spam
|
|
s.value = f # Stores a reference to f inside s
|
|
g = s.value # Returns stored reference
|
|
g = 4 # Reassign g to some other value
|
|
del f # Destroy f
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Now, ponder the resulting memory management issues. When objects are
|
|
created in the script, the objects are wrapped by newly created proxy
|
|
classes. That is, there is both a new proxy class instance and a new
|
|
instance of the underlying C++ class. In this example, both
|
|
<tt>f</tt> and <tt>s</tt> are created in this way. However, the
|
|
statement <tt>s.value</tt> is rather curious---when executed, a
|
|
pointer to <tt>f</tt> is stored inside another object. This means
|
|
that the scripting proxy class <em>AND</em> another C++ class share a
|
|
reference to the same object. To make matters even more interesting,
|
|
consider the statement <tt>g = s.value</tt>. When executed, this
|
|
creates a new proxy class <tt>g</tt> that provides a wrapper around the
|
|
C++ object stored in <tt>s.value</tt>. In general, there is no way to
|
|
know where this object came from---it could have been created by the
|
|
script, but it could also have been generated internally. In this
|
|
particular example, the assignment of <tt>g</tt> results in a second
|
|
proxy class for <tt>f</tt>. In other words, a reference to <tt>f</tt>
|
|
is now shared by two proxy classes <em>and</em> a C++ class.
|
|
</p>
|
|
|
|
<p>
|
|
Finally, consider what happens when objects are destroyed. In the
|
|
statement, <tt>g=4</tt>, the variable <tt>g</tt> is reassigned. In
|
|
many languages, this makes the old value of <tt>g</tt> available for
|
|
garbage collection. Therefore, this causes one of the proxy classes
|
|
to be destroyed. Later on, the statement <tt>del f</tt> destroys the
|
|
other proxy class. Of course, there is still a reference to the
|
|
original object stored inside another C++ object. What happens to it?
|
|
Is the object still valid?
|
|
</p>
|
|
|
|
<p>
|
|
To deal with memory management problems, proxy classes provide an API
|
|
for controlling ownership. In C++ pseudocode, ownership control might look
|
|
roughly like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class FooProxy {
|
|
public:
|
|
Foo *self;
|
|
int thisown;
|
|
|
|
FooProxy() {
|
|
self = new_Foo();
|
|
thisown = 1; // Newly created object
|
|
}
|
|
~FooProxy() {
|
|
if (thisown) delete_Foo(self);
|
|
}
|
|
...
|
|
// Ownership control API
|
|
void disown() {
|
|
thisown = 0;
|
|
}
|
|
void acquire() {
|
|
thisown = 1;
|
|
}
|
|
};
|
|
|
|
class FooPtrProxy: public FooProxy {
|
|
public:
|
|
FooPtrProxy(Foo *s) {
|
|
self = s;
|
|
thisown = 0;
|
|
}
|
|
};
|
|
|
|
class SpamProxy {
|
|
...
|
|
FooProxy *value_get() {
|
|
return FooPtrProxy(Spam_value_get(self));
|
|
}
|
|
void value_set(FooProxy *v) {
|
|
Spam_value_set(self, v->self);
|
|
v->disown();
|
|
}
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Looking at this code, there are a few central features:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Each proxy class keeps an extra flag to indicate ownership. C++ objects are only destroyed
|
|
if the ownership flag is set.
|
|
</li>
|
|
|
|
<li>When new objects are created in the target language, the ownership flag is set.
|
|
</li>
|
|
|
|
<li>When a reference to an internal C++ object is returned, it is wrapped by a proxy
|
|
class, but the proxy class does not have ownership.
|
|
</li>
|
|
|
|
<li>In certain cases, ownership is adjusted. For instance, when a value is assigned to the member of
|
|
a class, ownership is lost.
|
|
</li>
|
|
|
|
<li>Manual ownership control is provided by special <tt>disown()</tt> and <tt>acquire()</tt> methods.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Given the tricky nature of C++ memory management, it is impossible for proxy classes to automatically handle
|
|
every possible memory management problem. However, proxies do provide a mechanism for manual control that
|
|
can be used (if necessary) to address some of the more tricky memory management problems.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nn41">6.5.3 Language specific details</a></H3>
|
|
|
|
|
|
<p>
|
|
Language specific details on proxy classes are contained in the chapters describing each target language. This
|
|
chapter has merely introduced the topic in a very general way.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn6">6.6 Simple C++ wrapping</a></H2>
|
|
|
|
|
|
<p>
|
|
The following code shows a SWIG interface file for a simple C++
|
|
class.</p>
|
|
|
|
<div class="code"><pre>
|
|
%module list
|
|
%{
|
|
#include "list.h"
|
|
%}
|
|
|
|
// Very simple C++ example for linked list
|
|
|
|
class List {
|
|
public:
|
|
List();
|
|
~List();
|
|
int search(char *value);
|
|
void insert(char *);
|
|
void remove(char *);
|
|
char *get(int n);
|
|
int length;
|
|
static void print(List *l);
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
To generate wrappers for this class, SWIG first reduces the class to a collection of low-level C-style
|
|
accessor functions which are then used by the proxy classes.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nn7">6.6.1 Constructors and destructors</a></H3>
|
|
|
|
|
|
<p>
|
|
C++ constructors and destructors are translated into accessor
|
|
functions such as the following :</p>
|
|
|
|
<div class="code"><pre>
|
|
List * new_List(void) {
|
|
return new List;
|
|
}
|
|
void delete_List(List *l) {
|
|
delete l;
|
|
}
|
|
|
|
</pre></div>
|
|
|
|
<H3><a name="SWIGPlus_nn8">6.6.2 Default constructors, copy constructors and implicit destructors</a></H3>
|
|
|
|
|
|
<p>
|
|
Following the C++ rules for implicit constructor and destructors, SWIG
|
|
will automatically assume there is one even when they are not
|
|
explicitly declared in the class interface.
|
|
</p>
|
|
|
|
<p>
|
|
In general then:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
If a C++ class does not declare any explicit constructor, SWIG will
|
|
automatically generate a wrapper for one.
|
|
</li>
|
|
|
|
<li>
|
|
If a C++ class does not declare an explicit copy constructor, SWIG will
|
|
automatically generate a wrapper for one if <tt>%copyctor</tt> is used.
|
|
</li>
|
|
|
|
<li>
|
|
If a C++ class does not declare an explicit destructor, SWIG will
|
|
automatically generate a wrapper for one.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
And as in C++, a few rules that alters the previous behavior:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>A default constructor is not created if a class already defines a constructor with arguments.
|
|
</li>
|
|
|
|
<li>Default constructors are not generated for classes with pure virtual methods or for classes that
|
|
inherit from an abstract class, but don't provide definitions for all of the pure methods.
|
|
</li>
|
|
|
|
<li>A default constructor is not created unless all base classes support a
|
|
default constructor.
|
|
</li>
|
|
|
|
<li>Default constructors and implicit destructors are not created if a class
|
|
defines them in a <tt>private</tt> or <tt>protected</tt> section.
|
|
</li>
|
|
|
|
<li>Default constructors and implicit destructors are not created if any base
|
|
class defines a non-public default constructor or destructor.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
SWIG should never generate a default constructor, copy constructor or
|
|
default destructor wrapper for a class in which it is illegal to do so. In
|
|
some cases, however, it could be necessary (if the complete class
|
|
declaration is not visible from SWIG, and one of the above rules is
|
|
violated) or desired (to reduce the size of the final interface) by
|
|
manually disabling the implicit constructor/destructor generation.
|
|
</p>
|
|
|
|
<p>
|
|
To manually disable these, the <tt>%nodefaultctor</tt> and <tt>%nodefaultdtor</tt>
|
|
<a href="Customization.html#Customization_feature_flags">feature flag</a> directives
|
|
can be used. Note that these directives only affects the
|
|
implicit generation, and they have no effect if the default/copy
|
|
constructors or destructor are explicitly declared in the class
|
|
interface.
|
|
</p>
|
|
|
|
<p>
|
|
For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%nodefaultctor Foo; // Disable the default constructor for class Foo.
|
|
class Foo { // No default constructor is generated, unless one is declared
|
|
...
|
|
};
|
|
class Bar { // A default constructor is generated, if possible
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The directive <tt>%nodefaultctor</tt> can also be applied "globally", as in:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%nodefaultctor; // Disable creation of default constructors
|
|
class Foo { // No default constructor is generated, unless one is declared
|
|
...
|
|
};
|
|
class Bar {
|
|
public:
|
|
Bar(); // The default constructor is generated, since one is declared
|
|
};
|
|
%clearnodefaultctor; // Enable the creation of default constructors again
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The corresponding <tt>%nodefaultdtor</tt> directive can be used
|
|
to disable the generation of the default or implicit destructor, if
|
|
needed. Be aware, however, that this could lead to memory leaks in the
|
|
target language. Hence, it is recommended to use this directive only
|
|
in well known cases. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%nodefaultdtor Foo; // Disable the implicit/default destructor for class Foo.
|
|
class Foo { // No destructor is generated, unless one is declared
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<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>. 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
|
|
protected constructor/destructor is defined). In older versions of
|
|
SWIG, it was fairly common to simply remove or comment out
|
|
the private and protected sections of a class due to parser limitations.
|
|
However, this removal may now cause SWIG to erroneously generate constructors
|
|
for classes that define a constructor in those sections. Consider restoring
|
|
those sections in the interface or using <tt>%nodefault</tt> to fix the problem.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> The <tt>%nodefault</tt>
|
|
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 it.
|
|
</p>
|
|
|
|
|
|
<H3><a name="SWIGPlus_nn9">6.6.3 When constructor wrappers aren't created</a></H3>
|
|
|
|
|
|
<p>
|
|
If a class defines a constructor, SWIG normally tries to generate a wrapper for it. However, SWIG will
|
|
not generate a constructor wrapper if it thinks that it will result in illegal wrapper code. There are really
|
|
two cases where this might show up.
|
|
</p>
|
|
|
|
<p>
|
|
First, SWIG won't generate wrappers for protected or private constructors. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
protected:
|
|
Foo(); // Not wrapped.
|
|
public:
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Next, SWIG won't generate wrappers for a class if it appears to be abstract--that is, it has undefined
|
|
pure virtual methods. Here are some examples:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Bar {
|
|
public:
|
|
Bar(); // Not wrapped. Bar is abstract.
|
|
virtual void spam(void) = 0;
|
|
};
|
|
|
|
class Grok : public Bar {
|
|
public:
|
|
Grok(); // Not wrapped. No implementation of abstract spam().
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Some users are surprised (or confused) to find missing constructor wrappers in their interfaces. In almost
|
|
all cases, this is caused when classes are determined to be abstract. To see if this is the case, run SWIG with
|
|
all of its warnings turned on:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
% swig -Wall -python module.i
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this mode, SWIG will issue a warning for all abstract classes. It is possible to force a class to be
|
|
non-abstract using this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%feature("notabstract") Foo;
|
|
|
|
class Foo : public Bar {
|
|
public:
|
|
Foo(); // Generated no matter what---not abstract.
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
More information about <tt>%feature</tt> can be found in the <a href="Customization.html#Customization">Customization features</a> chapter.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nn10">6.6.4 Copy constructors</a></H3>
|
|
|
|
|
|
<p>
|
|
If a class defines more than one constructor, its behavior depends on the capabilities of the
|
|
target language. If overloading is supported, the copy constructor is accessible using
|
|
the normal constructor function. For example, if you have this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class List {
|
|
public:
|
|
List();
|
|
List(const List &); // Copy constructor
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
then the copy constructor can be used as follows:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
x = List() # Create a list
|
|
y = List(x) # Copy list x
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If the target language does not support overloading, then the copy constructor is available
|
|
through a special function like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
List *copy_List(List *f) {
|
|
return new List(*f);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Note:</b> For a class <tt>X</tt>, SWIG only treats a constructor as
|
|
a copy constructor if it can be applied to an object of type
|
|
<tt>X</tt> or <tt>X *</tt>. If more than one copy constructor is
|
|
defined, only the first definition that appears is used as the copy
|
|
constructor--other definitions will result in a name-clash.
|
|
Constructors such as <tt>X(const X &)</tt>, <tt>X(X &)</tt>, and
|
|
<tt>X(X *)</tt> are handled as copy constructors in SWIG.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> SWIG does <em>not</em> generate a copy constructor
|
|
wrapper unless one is explicitly declared in the class. This differs
|
|
from the treatment of default constructors and destructors.
|
|
However, copy constructor wrappers can be generated if using the <tt>copyctor</tt>
|
|
<a href="Customization.html#Customization_feature_flags">feature flag</a>. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%copyctor List;
|
|
|
|
class List {
|
|
public:
|
|
List();
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Will generate a copy constructor wrapper for <tt>List</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Compatibility note:</b> Special support for copy constructors was
|
|
not added until SWIG-1.3.12. In previous versions, copy constructors
|
|
could be wrapped, but they had to be renamed. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(CopyFoo) Foo::Foo(const Foo &);
|
|
|
|
class Foo {
|
|
public:
|
|
Foo();
|
|
Foo(const Foo &);
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
For backwards compatibility, SWIG does not perform any special
|
|
copy-constructor handling if the constructor has been manually
|
|
renamed. For instance, in the above example, the name of the
|
|
constructor is set to <tt>new_CopyFoo()</tt>. This is the same as in
|
|
older versions.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nn11">6.6.5 Member functions</a></H3>
|
|
|
|
|
|
<p>
|
|
All member functions are roughly translated into accessor functions like this :</p>
|
|
|
|
<div class="code"><pre>
|
|
int List_search(List *obj, char *value) {
|
|
return obj->search(value);
|
|
}
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
This translation is the same even if the member function has been
|
|
declared as <tt>virtual</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
It should be noted that SWIG does not <em>actually</em> create a C accessor
|
|
function in the code it generates. Instead, member access such as
|
|
<tt>obj->search(value)</tt> is directly inlined into the generated
|
|
wrapper functions. However, the name and calling convention of the
|
|
low-level procedural wrappers match the accessor function prototype described above.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nn12">6.6.6 Static members</a></H3>
|
|
|
|
|
|
<p>
|
|
Static member functions are called directly without making any special
|
|
transformations. For example, the static member function
|
|
<tt>print(List *l)</tt> directly invokes <tt>List::print(List *l)</tt>
|
|
in the generated wrapper code.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_member_data">6.6.7 Member data</a></H3>
|
|
|
|
|
|
<p>
|
|
Member data is handled in exactly the same manner as for C
|
|
structures. A pair of accessor functions are effectively created. For example
|
|
:</p>
|
|
|
|
<div class="code"><pre>
|
|
int List_length_get(List *obj) {
|
|
return obj->length;
|
|
}
|
|
int List_length_set(List *obj, int value) {
|
|
obj->length = value;
|
|
return value;
|
|
}
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
A read-only member can be created using the <tt>%immutable</tt> and <tt>%mutable</tt>
|
|
<a href="Customization.html#Customization_feature_flags">feature flag</a> directive.
|
|
For example, we probably wouldn't want
|
|
the user to change the length of a list so we could do the following
|
|
to make the value available, but read-only.</p>
|
|
|
|
<div class="code"><pre>
|
|
class List {
|
|
public:
|
|
...
|
|
%immutable;
|
|
int length;
|
|
%mutable;
|
|
...
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
Alternatively, you can specify an immutable member in advance like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%immutable List::length;
|
|
...
|
|
class List {
|
|
...
|
|
int length; // Immutable by above directive
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Similarly, all data attributes declared as <tt>const</tt> are wrapped as read-only members.
|
|
</p>
|
|
|
|
<p>
|
|
By default, SWIG uses the const reference typemaps for members that are primitive types.
|
|
There are some subtle issues when wrapping data members that are
|
|
not primitive types, such as classes. For instance, if you had another class like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
List items;
|
|
...
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
then the low-level accessor to the <tt>items</tt> member actually uses pointers.
|
|
For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
List *Foo_items_get(Foo *self) {
|
|
return &self->items;
|
|
}
|
|
void Foo_items_set(Foo *self, List *value) {
|
|
self->items = *value;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
More information about this can be found in the SWIG Basics chapter in the
|
|
<a href="SWIG.html#SWIG_structure_data_members">Structure data members</a> and
|
|
<a href="SWIG.html#SWIG_readonly_variables">Creating read-only variables</a> sections.
|
|
</p>
|
|
|
|
<p>
|
|
Additionally, any C++ type that is not assignable is also wrapped as a read-only member.
|
|
Consider the class below which is non-assignable due to the private assignment operator:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class NonAssignable {
|
|
private:
|
|
NonAssignable & operator=(const NonAssignable &);
|
|
public:
|
|
NonAssignable();
|
|
};
|
|
|
|
struct ImmutableVars {
|
|
NonAssignable non_assignable;
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The <tt>non_assignable</tt> member variable is immutable by default as SWIG detects that <tt>NonAssignable</tt> is not assignable.
|
|
SWIG must of course see the full type information in order to get this correct, otherwise you may have to use <tt>%immutable</tt> to make the variable read-only.
|
|
</p>
|
|
|
|
<p>
|
|
The wrapper code to generate the accessors for classes comes from the pointer typemaps.
|
|
This can be somewhat unnatural for some types.
|
|
For example, a user would expect the STL std::string class member variables to be wrapped as a string in the target language,
|
|
rather than a pointer to this class.
|
|
The const reference typemaps offer this type of marshalling, so there is a feature to tell SWIG to use the const reference typemaps rather than the pointer typemaps.
|
|
It is the naturalvar feature and can be used to effectively change the way accessors are generated to the following:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
const List &Foo_items_get(Foo *self) {
|
|
return self->items;
|
|
}
|
|
void Foo_items_set(Foo *self, const List &value) {
|
|
self->items = value;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The <tt>%naturalvar</tt> directive is a macro for, and hence equivalent to, <tt>%feature("naturalvar")</tt>. It can be used as follows:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// All List variables will use const List& typemaps
|
|
%naturalvar List;
|
|
|
|
// Only Foo::myList will use const List& typemaps
|
|
%naturalvar Foo::myList;
|
|
struct Foo {
|
|
List myList;
|
|
};
|
|
|
|
// All non-primitive types will use const reference typemaps
|
|
%naturalvar;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The observant reader will notice that <tt>%naturalvar</tt> works like any other
|
|
<a href="Customization.html#Customization_feature_flags">feature flag</a> directive but with some extra flexibility.
|
|
The first of the example usages above shows <tt>%naturalvar</tt> attaching to the <tt>myList</tt>'s variable type, that is the <tt>List</tt> class.
|
|
The second usage shows <tt>%naturalvar</tt> attaching to the variable name.
|
|
Hence the naturalvar feature can be used on either the variable's name or type.
|
|
Note that using the naturalvar feature on a variable's name overrides any naturalvar feature attached to the variable's type.
|
|
</p>
|
|
|
|
<p>
|
|
It is generally a good idea to use this feature globally as the reference typemaps have extra NULL checking compared to the pointer typemaps.
|
|
A pointer can be NULL, whereas a reference cannot, so the extra checking ensures that the target language user does not pass in a value that translates
|
|
to a NULL pointer and thereby preventing any potential NULL pointer dereferences.
|
|
The <tt>%naturalvar</tt> feature will apply to global variables in addition to member variables in some language modules, eg C# and Java.
|
|
</p>
|
|
|
|
<p>
|
|
The naturalvar behavior can also be turned on as a global setting via the <tt>-naturalvar</tt> commandline option
|
|
or the module mode option, <tt>%module(naturalvar=1)</tt>.
|
|
However, any use of <tt>%feature("naturalvar")</tt> will override the global setting.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Compatibility note:</b> The <tt>%naturalvar</tt> feature was introduced in SWIG-1.3.28, prior to which it was necessary to manually apply the const reference
|
|
typemaps, eg <tt>%apply const std::string & { std::string * }</tt>, but this example would also apply the typemaps to methods taking a <tt>std::string</tt> pointer.
|
|
</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
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
struct Foo {
|
|
size_t len;
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
and nothing was known about <tt>size_t</tt>, then accessors would be
|
|
written to work with <tt>size_t *</tt>. Starting in SWIG-1.3.12, this
|
|
behavior has been modified. Specifically, pointers will <em>only</em>
|
|
be used if SWIG knows that a datatype corresponds to a structure or
|
|
class. Therefore, the above code would be wrapped into accessors
|
|
involving <tt>size_t</tt>. This change is subtle, but it smooths over
|
|
a few problems related to structure wrapping and some of SWIG's
|
|
customization features.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn15">6.7 Protection</a></H2>
|
|
|
|
|
|
<p>
|
|
SWIG wraps class members that are public following the C++
|
|
conventions, i.e., by explicit public declaration or by the use of
|
|
<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
|
|
constructors and destructors. Directors could also modify the way
|
|
non-public virtual protected members are treated.
|
|
</p>
|
|
|
|
<p>
|
|
By default, members of a class definition are assumed to be private
|
|
until you explicitly give a `<tt>public:</tt>' declaration (This is
|
|
the same convention used by C++).
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn16">6.8 Enums and constants</a></H2>
|
|
|
|
|
|
<p>
|
|
Enumerations and constants are handled differently by the different language modules and are described in detail in the appropriate language chapter.
|
|
However, many languages map enums and constants in a class definition
|
|
into constants with the classname as a prefix. For example :</p>
|
|
|
|
<div class="code"><pre>
|
|
class Swig {
|
|
public:
|
|
enum {ALE, LAGER, PORTER, STOUT};
|
|
};
|
|
|
|
</pre></div>
|
|
<p>
|
|
Generates the following set of constants in the target scripting language :</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
Swig_ALE = Swig::ALE
|
|
Swig_LAGER = Swig::LAGER
|
|
Swig_PORTER = Swig::PORTER
|
|
Swig_STOUT = Swig::STOUT
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
Members declared as <tt>const</tt> are wrapped as read-only members and do not create constants.
|
|
</p>
|
|
|
|
<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 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 X;
|
|
class Y;
|
|
class C {
|
|
// Friend classes have no effect on generated wrappers
|
|
friend class X;
|
|
friend Y;
|
|
...
|
|
};
|
|
</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> function definition results in wrapper code
|
|
equivalent to one generated for the following:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Buddy {
|
|
int val;
|
|
friend int blah(Buddy *b);
|
|
public:
|
|
...
|
|
};
|
|
|
|
int blah(Buddy *b) { return b->val; }
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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(Buddy *b);
|
|
// Not: %ignore bar::Buddy::blah(Buddy *b);
|
|
|
|
namespace bar {
|
|
class Buddy {
|
|
int val;
|
|
friend int blah(Buddy *b) { return b->val; }
|
|
public:
|
|
...
|
|
};
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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>
|
|
|
|
|
|
<p>
|
|
C++ references are supported, but SWIG transforms them back into pointers. For example,
|
|
a declaration like this :</p>
|
|
|
|
<div class="code"><pre>
|
|
class Foo {
|
|
public:
|
|
double bar(double &a);
|
|
}
|
|
</pre></div>
|
|
|
|
<p>
|
|
has a low-level accessor
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
double Foo_bar(Foo *obj, double *a) {
|
|
obj->bar(*a);
|
|
}
|
|
</pre></div>
|
|
|
|
<p>
|
|
As a special case, most language modules pass <tt>const</tt> references to primitive datatypes (<tt>int</tt>, <tt>short</tt>,
|
|
<tt>float</tt>, etc.) by value instead of pointers. For example, if you have a function like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void foo(const int &x);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
it is called from a script as follows:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
foo(3) # Notice pass by value
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Functions that return a reference are remapped to return a pointer instead.
|
|
For example:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
class Bar {
|
|
public:
|
|
Foo &spam();
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Generates an accessor like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
Foo *Bar_spam(Bar *obj) {
|
|
Foo &result = obj->spam();
|
|
return &result;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
However, functions that return <tt>const</tt> references to primitive datatypes (<tt>int</tt>, <tt>short</tt>, etc.) normally
|
|
return the result as a value rather than a pointer. For example, a function like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
const int &bar();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
will return integers such as 37 or 42 in the target scripting language rather than a pointer to an integer.
|
|
</p>
|
|
|
|
<P>
|
|
Don't return references to objects allocated as local variables on the
|
|
stack. SWIG doesn't make a copy of the objects so this will probably
|
|
cause your program to crash.
|
|
|
|
|
|
|
|
<p>
|
|
<b>Note:</b> The special treatment for references to primitive datatypes is necessary to provide
|
|
more seamless integration with more advanced C++ wrapping applications---especially related to
|
|
templates and the STL. This was first added in SWIG-1.3.12.
|
|
</p>
|
|
|
|
|
|
<H2><a name="SWIGPlus_nn19">6.11 Pass and return by value</a></H2>
|
|
|
|
|
|
<p>
|
|
Occasionally, a C++ program will pass and return class objects by value. For example, a function
|
|
like this might appear:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
Vector cross_product(Vector a, Vector b);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If no information is supplied about <tt>Vector</tt>, SWIG creates a wrapper function similar to the
|
|
following:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
Vector *wrap_cross_product(Vector *a, Vector *b) {
|
|
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 default constructor and a 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>
|
|
If <tt>Vector</tt> is defined as a class in the interface, but it does not
|
|
support a default constructor and an assignment operator, SWIG changes the wrapper code by encapsulating
|
|
the arguments inside a special C++ template wrapper class, through a process
|
|
called the "Fulton Transform". This produces a wrapper that looks like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
Vector cross_product(Vector *a, Vector *b) {
|
|
SwigValueWrapper<Vector> x;
|
|
SwigValueWrapper<Vector> y;
|
|
SwigValueWrapper<Vector> r;
|
|
x = *a;
|
|
y = *b;
|
|
r = cross_product(x, y);
|
|
return new Vector(r);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
This transformation is a little sneaky, but it provides support for
|
|
pass-by-value even when a class is not default constructible nor assignable
|
|
and it makes it possible to properly support a number of SWIG's
|
|
customization options. The definition of <tt>SwigValueWrapper</tt>
|
|
can be found by reading the SWIG wrapper code. This class is really nothing more than a thin
|
|
wrapper around a pointer.
|
|
</p>
|
|
|
|
<p>
|
|
Although SWIG usually detects the classes to which the Fulton Transform should
|
|
be applied, in some situations it's necessary to override it. That's done with
|
|
<tt>%feature("valuewrapper")</tt> to ensure it is used and <tt>%feature("novaluewrapper")</tt>
|
|
to ensure it is not used:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%feature("novaluewrapper") A;
|
|
class A;
|
|
|
|
%feature("valuewrapper") B;
|
|
struct B {
|
|
B();
|
|
// ....
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
It is well worth considering turning this feature on for classes that do have a default constructor.
|
|
It will remove a redundant constructor call at the point of the variable declaration in the wrapper,
|
|
so will generate notably better performance for large objects or for classes with expensive construction.
|
|
Alternatively consider returning a reference or a pointer.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> this transformation has no effect on typemaps
|
|
or any other part of SWIG---it should be transparent except that you
|
|
may see this code when reading the SWIG output file.
|
|
</p>
|
|
|
|
<p>
|
|
<b>
|
|
Note: </b>This template transformation is new in SWIG-1.3.11 and may be refined in
|
|
future SWIG releases. In practice, it is only absolutely necessary to do this for
|
|
classes that don't define a default constructor.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> The use of this template only occurs when objects are passed or returned by value.
|
|
It is not used for C++ pointers or references.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn20">6.12 Inheritance</a></H2>
|
|
|
|
|
|
<p>
|
|
SWIG supports C++ inheritance of classes and allows both single and
|
|
multiple inheritance, as limited or allowed by the target
|
|
language. The SWIG type-checker knows about the relationship between
|
|
base and derived classes and allows pointers to any object of a
|
|
derived class to be used in functions of a base class. The
|
|
type-checker properly casts pointer values and is safe to use with
|
|
multiple inheritance.
|
|
</p>
|
|
|
|
<p> SWIG treats private or protected inheritance as close to the C++
|
|
spirit, and target language capabilities, as possible. In most
|
|
cases, this means that SWIG will parse the non-public inheritance
|
|
declarations, but that will have no effect in the generated code,
|
|
besides the implicit policies derived for constructors and
|
|
destructors.
|
|
</p>
|
|
|
|
|
|
<p>
|
|
The following example shows how SWIG handles inheritance. For clarity,
|
|
the full C++ code has been omitted.</p>
|
|
|
|
<div class="code"><pre>
|
|
// shapes.i
|
|
%module shapes
|
|
%{
|
|
#include "shapes.h"
|
|
%}
|
|
|
|
class Shape {
|
|
public:
|
|
double x, y;
|
|
virtual double area() = 0;
|
|
virtual double perimeter() = 0;
|
|
void set_location(double x, double y);
|
|
};
|
|
class Circle : public Shape {
|
|
public:
|
|
Circle(double radius);
|
|
~Circle();
|
|
double area();
|
|
double perimeter();
|
|
};
|
|
class Square : public Shape {
|
|
public:
|
|
Square(double size);
|
|
~Square();
|
|
double area();
|
|
double perimeter();
|
|
}
|
|
</pre></div>
|
|
|
|
<p>
|
|
When wrapped into Python, we can perform the following operations (shown using the low level Python accessors):
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
$ python
|
|
>>> import shapes
|
|
>>> circle = shapes.new_Circle(7)
|
|
>>> square = shapes.new_Square(10)
|
|
>>> print(shapes.Circle_area(circle))
|
|
153.93804004599999757
|
|
>>> print(shapes.Shape_area(circle))
|
|
153.93804004599999757
|
|
>>> print(shapes.Shape_area(square))
|
|
100.00000000000000000
|
|
>>> shapes.Shape_set_location(square, 2, -3)
|
|
>>> print(shapes.Shape_perimeter(square))
|
|
40.00000000000000000
|
|
>>>
|
|
</pre></div>
|
|
|
|
<p>
|
|
In this example, Circle and Square objects have been created. Member
|
|
functions can be invoked on each object by making calls to
|
|
<tt>Circle_area</tt>, <tt>Square_area</tt>, and so on. However, the same
|
|
results can be accomplished by simply using the <tt>Shape_area</tt>
|
|
function on either object.
|
|
</p>
|
|
|
|
<p>
|
|
One important point concerning inheritance is that the low-level
|
|
accessor functions are only generated for classes in which they are
|
|
actually declared. For instance, in the above example, the method
|
|
<tt>set_location()</tt> is only accessible as
|
|
<tt>Shape_set_location()</tt> and not as
|
|
<tt>Circle_set_location()</tt> or <tt>Square_set_location()</tt>. Of
|
|
course, the <tt>Shape_set_location()</tt> function will accept any
|
|
kind of object derived from Shape. Similarly, accessor functions for
|
|
the attributes <tt>x</tt> and <tt>y</tt> are generated as
|
|
<tt>Shape_x_get()</tt>, <tt>Shape_x_set()</tt>,
|
|
<tt>Shape_y_get()</tt>, and <tt>Shape_y_set()</tt>. Functions such as
|
|
<tt>Circle_x_get()</tt> are not available--instead you should use
|
|
<tt>Shape_x_get()</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
Note that there is a one to one correlation between the low-level accessor functions and
|
|
the proxy methods and therefore there is also a one to one correlation between
|
|
the C++ class methods and the generated proxy class methods.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> For the best results, SWIG requires all
|
|
base classes to be defined in an interface. Otherwise, you may get a
|
|
warning message like this:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:18: Warning 401: Nothing known about base class 'Foo'. Ignored.
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If any base class is undefined, SWIG still generates correct type
|
|
relationships. For instance, a function accepting a <tt>Foo *</tt>
|
|
will accept any object derived from <tt>Foo</tt> regardless of whether
|
|
or not SWIG actually wrapped the <tt>Foo</tt> class. If you really
|
|
don't want to generate wrappers for the base class, but you want to
|
|
silence the warning, you might consider using the <tt>%import</tt>
|
|
directive to include the file that defines <tt>Foo</tt>.
|
|
<tt>%import</tt> simply gathers type information, but doesn't generate
|
|
wrappers. Alternatively, you could just define <tt>Foo</tt> as an empty class
|
|
in the SWIG interface or use
|
|
<a href="Warnings.html#Warnings_suppression">warning suppression</a>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> <tt>typedef</tt>-names <em>can</em> be used as base classes. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
...
|
|
};
|
|
|
|
typedef Foo FooObj;
|
|
class Bar : public FooObj { // Ok. Base class is Foo
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Similarly, <tt>typedef</tt> allows unnamed structures to be used as base classes. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
typedef struct {
|
|
...
|
|
} Foo;
|
|
|
|
class Bar : public Foo { // Ok.
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Compatibility Note:</b> Starting in version 1.3.7, SWIG only
|
|
generates low-level accessor wrappers for the declarations that are
|
|
actually defined in each class. This differs from SWIG1.1 which used
|
|
to inherit all of the declarations defined in base classes and
|
|
regenerate specialized accessor functions such as
|
|
<tt>Circle_x_get()</tt>, <tt>Square_x_get()</tt>,
|
|
<tt>Circle_set_location()</tt>, and <tt>Square_set_location()</tt>.
|
|
This behavior resulted in huge amounts of replicated code for large
|
|
class hierarchies and made it awkward to build applications spread
|
|
across multiple modules (since accessor functions are duplicated in
|
|
every single module). It is also unnecessary to have such wrappers
|
|
when advanced features like proxy classes are used.
|
|
|
|
<b>Note:</b> Further optimizations are enabled when using the
|
|
<tt>-fvirtual</tt> option, which avoids the regenerating of wrapper
|
|
functions for virtual members that are already defined in a base
|
|
class.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn21">6.13 A brief discussion of multiple inheritance, pointers, and type checking</a></H2>
|
|
|
|
|
|
<p>
|
|
When a target scripting language refers to a C++ object, it normally
|
|
uses a tagged pointer object that contains both the value of the
|
|
pointer and a type string. For example, in Tcl, a C++ pointer might
|
|
be encoded as a string like this:
|
|
</p>
|
|
|
|
<div class="diagram">
|
|
<pre>
|
|
_808fea88_p_Circle
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
A somewhat common question is whether or not the type-tag could be safely
|
|
removed from the pointer. For instance, to get better performance, could you
|
|
strip all type tags and just use simple integers instead?
|
|
</p>
|
|
|
|
<p>
|
|
In general, the answer to this question is no. In the wrappers, all
|
|
pointers are converted into a common data representation in the target
|
|
language. Typically this is the equivalent of casting a pointer to <tt>void *</tt>.
|
|
This means that any C++ type information associated with the pointer is
|
|
lost in the conversion.
|
|
</p>
|
|
|
|
<p>
|
|
The problem with losing type information is that it is needed to
|
|
properly support many advanced C++ features--especially multiple
|
|
inheritance. For example, suppose you had code like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class A {
|
|
public:
|
|
int x;
|
|
};
|
|
|
|
class B {
|
|
public:
|
|
int y;
|
|
};
|
|
|
|
class C : public A, public B {
|
|
};
|
|
|
|
int A_function(A *a) {
|
|
return a->x;
|
|
}
|
|
|
|
int B_function(B *b) {
|
|
return b->y;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Now, consider the following code that uses <tt>void *</tt>.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
C *c = new C();
|
|
void *p = (void *) c;
|
|
...
|
|
int x = A_function((A *) p);
|
|
int y = B_function((B *) p);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this code, both <tt>A_function()</tt> and <tt>B_function()</tt> may
|
|
legally accept an object of type <tt>C *</tt> (via inheritance).
|
|
However, one of the functions will always return the wrong result when
|
|
used as shown. The reason for this is that even though <tt>p</tt>
|
|
points to an object of type <tt>C</tt>, the casting operation doesn't
|
|
work like you would expect. Internally, this has to do with the data
|
|
representation of <tt>C</tt>. With multiple inheritance, the data from
|
|
each base class is stacked together. For example:
|
|
</p>
|
|
|
|
<div class="diagram">
|
|
<pre>
|
|
------------ <--- (C *), (A *)
|
|
| A |
|
|
|------------| <--- (B *)
|
|
| B |
|
|
------------
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Because of this stacking, a pointer of type <tt>C *</tt> may change
|
|
value when it is converted to a <tt>A *</tt> or <tt>B *</tt>.
|
|
However, this adjustment does <em>not</em> occur if you are converting from a
|
|
<tt>void *</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
The use of type tags marks all pointers with the real type of the
|
|
underlying object. This extra information is then used by SWIG
|
|
generated wrappers to correctly cast pointer values under inheritance
|
|
(avoiding the above problem).
|
|
</p>
|
|
|
|
<p>
|
|
Some of the language modules are able to solve the problem by storing multiple instances of the pointer, for example, <tt>A *</tt>,
|
|
in the A proxy class as well as <tt>C *</tt> in the C proxy class. The correct cast can then be made by choosing the correct <tt>void *</tt>
|
|
pointer to use and is guaranteed to work as the cast to a void pointer and back to the same type does not lose any type information:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
C *c = new C();
|
|
void *p = (void *) c;
|
|
void *pA = (void *) c;
|
|
void *pB = (void *) c;
|
|
...
|
|
int x = A_function((A *) pA);
|
|
int y = B_function((B *) pB);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In practice, the pointer is held as an integral number in the target language proxy class.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_default_args">6.14 Default arguments</a></H2>
|
|
|
|
|
|
<p>
|
|
SWIG will wrap all types of functions that have default arguments. For example member functions:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
void bar(int x, int y = 3, int z = 4);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
SWIG handles default arguments by generating an extra overloaded method for each defaulted argument.
|
|
SWIG is effectively handling methods with default arguments as if it was wrapping the equivalent overloaded methods.
|
|
Thus for the example above, it is as if we had instead given the following to SWIG:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
void bar(int x, int y, int z);
|
|
void bar(int x, int y);
|
|
void bar(int x);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The wrappers produced are exactly the same as if the above code was instead fed into SWIG.
|
|
Details of this are covered 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>
|
|
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.
|
|
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>
|
|
In many language modules, SWIG provides partial support for overloaded functions, methods, and
|
|
constructors. For example, if you supply SWIG with overloaded functions like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void foo(int x) {
|
|
printf("x is %d\n", x);
|
|
}
|
|
void foo(char *x) {
|
|
printf("x is '%s'\n", x);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The function is used in a completely natural way. For example:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
>>> foo(3)
|
|
x is 3
|
|
>>> foo("hello")
|
|
x is 'hello'
|
|
>>>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Overloading works in a similar manner for methods and constructors. For example if you have
|
|
this code,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
Foo();
|
|
Foo(const Foo &); // Copy constructor
|
|
void bar(int x);
|
|
void bar(char *s, int y);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
it might be used like this
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
>>> f = Foo() # Create a Foo
|
|
>>> f.bar(3)
|
|
>>> g = Foo(f) # Copy Foo
|
|
>>> f.bar("hello", 2)
|
|
</pre>
|
|
</div>
|
|
|
|
<H3><a name="SWIGPlus_nn24">6.15.1 Dispatch function generation</a></H3>
|
|
|
|
|
|
<p>
|
|
The implementation of overloaded functions and methods is somewhat
|
|
complicated due to the dynamic nature of scripting languages. Unlike
|
|
C++, which binds overloaded methods at compile time, SWIG must
|
|
determine the proper function as a runtime check for scripting language targets. This check is
|
|
further complicated by the typeless nature of certain scripting languages. For instance,
|
|
in Tcl, all types are simply strings. Therefore, if you have two overloaded functions
|
|
like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void foo(char *x);
|
|
void foo(int x);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
the order in which the arguments are checked plays a rather critical role.
|
|
</p>
|
|
|
|
<p>
|
|
For statically typed languages, SWIG uses the language's method overloading mechanism.
|
|
To implement overloading for the scripting languages, SWIG generates a dispatch function that checks the
|
|
number of passed arguments and their types. To create this function, SWIG
|
|
first examines all of the overloaded methods and ranks them according
|
|
to the following rules:
|
|
</p>
|
|
|
|
<ol>
|
|
<li><b>Number of required arguments.</b> Methods are sorted by increasing number of
|
|
required arguments.
|
|
</li>
|
|
<li><p><b>Argument type precedence.</b> All C++ datatypes are assigned a numeric type precedence value
|
|
(which is determined by the language module).</p>
|
|
|
|
<div class="diagram">
|
|
<pre>
|
|
Type Precedence
|
|
---------------- ----------
|
|
TYPE * 0 (High)
|
|
void * 20
|
|
Integers 40
|
|
Floating point 60
|
|
char 80
|
|
Strings 100 (Low)
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Using these precedence values, overloaded methods with the same number of required arguments are sorted in increased
|
|
order of precedence values.
|
|
</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>
|
|
This may sound very confusing, but an example will help. Consider the following collection of
|
|
overloaded methods:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void foo(double);
|
|
void foo(int);
|
|
void foo(Bar *);
|
|
void foo();
|
|
void foo(int x, int y, int z, int w);
|
|
void foo(int x, int y, int z = 3);
|
|
void foo(double x, double y);
|
|
void foo(double x, Bar *z);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The first rule simply ranks the functions by required argument count.
|
|
This would produce the following list:
|
|
</p>
|
|
|
|
<div class="diagram">
|
|
<pre>
|
|
rank
|
|
-----
|
|
[0] foo()
|
|
[1] foo(double);
|
|
[2] foo(int);
|
|
[3] foo(Bar *);
|
|
[4] foo(int x, int y, int z = 3);
|
|
[5] foo(double x, double y)
|
|
[6] foo(double x, Bar *z)
|
|
[7] foo(int x, int y, int z, int w);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The second rule, simply refines the ranking by looking at argument type precedence values.
|
|
</p>
|
|
|
|
<div class="diagram">
|
|
<pre>
|
|
rank
|
|
-----
|
|
[0] foo()
|
|
[1] foo(Bar *);
|
|
[2] foo(int);
|
|
[3] foo(double);
|
|
[4] foo(int x, int y, int z = 3);
|
|
[5] foo(double x, Bar *z)
|
|
[6] foo(double x, double y)
|
|
[7] foo(int x, int y, int z, int w);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Finally, to generate the dispatch function, the arguments passed to an overloaded method are simply
|
|
checked in the same order as they appear in this ranking.
|
|
</p>
|
|
|
|
<p>
|
|
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>
|
|
|
|
|
|
<p>
|
|
Regrettably, SWIG is not able to support every possible use of valid C++ overloading. Consider
|
|
the following example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void foo(int x);
|
|
void foo(long x);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In C++, this is perfectly legal. However, in a scripting language, there is generally only one kind of integer
|
|
object. Therefore, which one of these functions do you pick? Clearly, there is no way to truly make a distinction
|
|
just by looking at the value of the integer itself (<tt>int</tt> and <tt>long</tt> may even be the same precision).
|
|
Therefore, when SWIG encounters this situation, it may generate a warning message like this for scripting languages:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:4: Warning 509: Overloaded method foo(long) effectively ignored,
|
|
example.i:3: Warning 509: as it is shadowed by foo(int).
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
or for statically typed languages like Java:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:4: Warning 516: Overloaded method foo(long) ignored,
|
|
example.i:3: Warning 516: using foo(int) instead.
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
This means that the second overloaded function will be inaccessible
|
|
from a scripting interface or the method won't be wrapped at all.
|
|
This is done as SWIG does not know how to disambiguate it from an earlier method.
|
|
</p>
|
|
|
|
<p>
|
|
Ambiguity problems are known to arise in the following situations:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Integer conversions. Datatypes such as <tt>int</tt>, <tt>long</tt>, and <tt>short</tt> cannot be disambiguated in some languages. Shown above.
|
|
</li>
|
|
|
|
<li>Floating point conversion. <tt>float</tt> and <tt>double</tt> can not be disambiguated in some languages.
|
|
</li>
|
|
|
|
<li>Pointers and references. For example, <tt>Foo *</tt> and <tt>Foo &</tt>.
|
|
</li>
|
|
|
|
<li>Pointers and arrays. For example, <tt>Foo *</tt> and <tt>Foo [4]</tt>.
|
|
</li>
|
|
|
|
<li>Pointers and instances. For example, <tt>Foo</tt> and <tt>Foo *</tt>. Note: SWIG converts all
|
|
instances to pointers.
|
|
</li>
|
|
|
|
<li>Qualifiers. For example, <tt>const Foo *</tt> and <tt>Foo *</tt>.
|
|
</li>
|
|
|
|
<li>Default vs. non default arguments. For example, <tt>foo(int a, int b)</tt> and <tt>foo(int a, int b = 3)</tt>.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
When an ambiguity arises, methods are checked in the same order as they appear in the interface file.
|
|
Therefore, earlier methods will shadow methods that appear later.
|
|
</p>
|
|
|
|
<p>
|
|
When wrapping an overloaded function, there is a chance that you will get a warning message like this:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:3: Warning 467: Overloaded foo(int) not supported (incomplete type checking rule -
|
|
no precedence level in typecheck typemap for 'int').
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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="https://www.swig.org/bugs.html">SWIG bug tracking database</a>
|
|
if this is due to one of the typemaps supplied with SWIG.
|
|
</p>
|
|
|
|
<p>
|
|
If you get an error message such as the following,
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
foo.i:6. Overloaded declaration ignored. Spam::foo(double )
|
|
foo.i:5. Previous declaration is Spam::foo(int )
|
|
foo.i:7. Overloaded declaration ignored. Spam::foo(Bar *, Spam *, int )
|
|
foo.i:5. Previous declaration is Spam::foo(int )
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
it means that the target language module has not yet implemented support for overloaded
|
|
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 Renaming and ambiguity resolution</a></H3>
|
|
|
|
|
|
<p>
|
|
If an ambiguity in overload resolution occurs or if a module doesn't
|
|
allow overloading, there are a few strategies for dealing with the
|
|
problem. First, you can tell SWIG to ignore one of the methods. This
|
|
is easy---simply use the <tt>%ignore</tt> directive. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%ignore foo(long);
|
|
|
|
void foo(int);
|
|
void foo(long); // Ignored. Oh well.
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The other alternative is to rename one of the methods. This can be
|
|
done using <tt>%rename</tt>. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename("foo_short") foo(short);
|
|
%rename(foo_long) foo(long);
|
|
|
|
void foo(int);
|
|
void foo(short); // Accessed as foo_short()
|
|
void foo(long); // Accessed as foo_long()
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Note that the quotes around the new name are optional, however,
|
|
should the new name be a C/C++ keyword they would be essential in order to avoid a parsing error.
|
|
The <tt>%ignore</tt> and <tt>%rename</tt> directives are both rather powerful
|
|
in their ability to match declarations. When used in their simple form, they apply to
|
|
both global functions and methods. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
/* Forward renaming declarations */
|
|
%rename(foo_i) foo(int);
|
|
%rename(foo_d) foo(double);
|
|
...
|
|
void foo(int); // Becomes 'foo_i'
|
|
void foo(char *c); // Stays 'foo' (not renamed)
|
|
|
|
class Spam {
|
|
public:
|
|
void foo(int); // Becomes 'foo_i'
|
|
void foo(double); // Becomes 'foo_d'
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If you only want the renaming to apply to a certain scope, the C++ scope resolution operator (::) can be used.
|
|
For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(foo_i) ::foo(int); // Only rename foo(int) in the global scope.
|
|
// (will not rename class members)
|
|
|
|
%rename(foo_i) Spam::foo(int); // Only rename foo(int) in class Spam
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When a renaming operator is applied to a class as in <tt>Spam::foo(int)</tt>, it is applied to
|
|
that class and all derived classes. This can be used to apply a consistent renaming across
|
|
an entire class hierarchy with only a few declarations. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(foo_i) Spam::foo(int);
|
|
%rename(foo_d) Spam::foo(double);
|
|
|
|
class Spam {
|
|
public:
|
|
virtual void foo(int); // Renamed to foo_i
|
|
virtual void foo(double); // Renamed to foo_d
|
|
...
|
|
};
|
|
|
|
class Bar : public Spam {
|
|
public:
|
|
virtual void foo(int); // Renamed to foo_i
|
|
virtual void foo(double); // Renamed to foo_d
|
|
...
|
|
};
|
|
|
|
class Grok : public Bar {
|
|
public:
|
|
virtual void foo(int); // Renamed to foo_i
|
|
virtual void foo(double); // Renamed to foo_d
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
It is also possible to include <tt>%rename</tt> specifications in the
|
|
class definition itself. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Spam {
|
|
%rename(foo_i) foo(int);
|
|
%rename(foo_d) foo(double);
|
|
public:
|
|
virtual void foo(int); // Renamed to foo_i
|
|
virtual void foo(double); // Renamed to foo_d
|
|
...
|
|
};
|
|
|
|
class Bar : public Spam {
|
|
public:
|
|
virtual void foo(int); // Renamed to foo_i
|
|
virtual void foo(double); // Renamed to foo_d
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this case, the <tt>%rename</tt> directives still get applied across the entire
|
|
inheritance hierarchy, but it's no longer necessary to explicitly specify the
|
|
class prefix <tt>Spam::</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
A special form of <tt>%rename</tt> can be used to apply a renaming just to class
|
|
members (of all classes):
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(foo_i) *::foo(int); // Only rename foo(int) if it appears in a class.
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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="https://www.swig.org/mail.html">swig-devel mailing list</a>.
|
|
</p>
|
|
|
|
<p>
|
|
Although this discussion has primarily focused on <tt>%rename</tt> all of the same rules
|
|
also apply to <tt>%ignore</tt>. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%ignore foo(double); // Ignore all foo(double)
|
|
%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>
|
|
|
|
<p>
|
|
When applied to a base class, <tt>%ignore</tt> forces all definitions in derived classes
|
|
to disappear. For example, <tt>%ignore Spam::foo(double)</tt> will eliminate <tt>foo(double)</tt> in
|
|
<tt>Spam</tt> and all classes derived from <tt>Spam</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Notes on %rename and %ignore:</b>
|
|
</p>
|
|
|
|
<ul>
|
|
<li><p>Since, the <tt>%rename</tt> declaration is used to declare a renaming in advance, it can be
|
|
placed at the start of an interface file. This makes it possible to apply a consistent name
|
|
resolution without having to modify header files. For example:</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%module foo
|
|
|
|
/* Rename these overloaded functions */
|
|
%rename(foo_i) foo(int);
|
|
%rename(foo_d) foo(double);
|
|
|
|
%include "header.h"
|
|
</pre>
|
|
</div>
|
|
</li>
|
|
|
|
<li><p>The scope qualifier (::) can also be used on simple names. For example:</p>
|
|
<div class="code">
|
|
<pre>
|
|
%rename(bar) ::foo; // Rename foo to bar in global scope only
|
|
%rename(bar) Spam::foo; // Rename foo to bar in class Spam only
|
|
%rename(bar) *::foo; // Rename foo in classes only
|
|
</pre>
|
|
</div>
|
|
</li>
|
|
|
|
<li><p>Name matching tries to find the most specific match that is
|
|
defined. A qualified name such as <tt>Spam::foo</tt> always has
|
|
higher precedence than an unqualified name <tt>foo</tt>.
|
|
<tt>Spam::foo</tt> has higher precedence than <tt>*::foo</tt> and
|
|
<tt>*::foo</tt> has higher precedence than <tt>foo</tt>. A
|
|
parameterized name has higher precedence than an unparameterized name
|
|
within the same scope level. However, an unparameterized name with a
|
|
scope qualifier has higher precedence than a parameterized name in
|
|
global scope (e.g., a renaming of <tt>Spam::foo</tt> takes precedence
|
|
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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(bar) foo;
|
|
%rename(foo_i) Spam::foo(int);
|
|
%rename(Foo) Spam::foo;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
and this
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(Foo) Spam::foo;
|
|
%rename(bar) foo;
|
|
%rename(foo_i) Spam::foo(int);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
(the declarations are not stored in a linked list and order has no
|
|
importance). Of course, a repeated <tt>%rename</tt> directive will
|
|
change the setting for a previous <tt>%rename</tt> directive if exactly the
|
|
same name, scope, and parameters are supplied.
|
|
</p>
|
|
</li>
|
|
|
|
<li>For multiple inheritance where renaming rules are defined for multiple base classes,
|
|
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 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>
|
|
class Spam {
|
|
public:
|
|
...
|
|
void bar() const;
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
the declaration
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(name) Spam::bar();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
will not apply as there is no unqualified member <tt>bar()</tt>. The following will apply the rename as
|
|
the qualifier matches correctly:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(name) Spam::bar() const;
|
|
</pre>
|
|
</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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Spam {
|
|
public:
|
|
...
|
|
void bar(); // Unqualified member
|
|
void bar() const; // Qualified member
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
%rename can then be used to target each of the overloaded methods individually.
|
|
For example we can give them separate names in the target language:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(name1) Spam::bar();
|
|
%rename(name2) Spam::bar() const;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Similarly, if you
|
|
merely wanted to ignore one of the declarations, use <tt>%ignore</tt>
|
|
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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%ignore Spam::bar() const; // Ignore bar() const, but leave other bar() alone
|
|
</pre>
|
|
</div>
|
|
|
|
</li>
|
|
|
|
<li><p>
|
|
Currently no resolution is performed in order to match function parameters. This means function parameter types must match exactly.
|
|
For example, namespace qualifiers and typedefs will not work. The following usage of typedefs demonstrates this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
typedef int Integer;
|
|
|
|
%rename(foo_i) foo(int);
|
|
|
|
class Spam {
|
|
public:
|
|
void foo(Integer); // Stays 'foo' (not renamed)
|
|
};
|
|
class Ham {
|
|
public:
|
|
void foo(int); // Renamed to foo_i
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<li><p>
|
|
The name matching rules also use default arguments for finer control when wrapping methods that have default arguments.
|
|
Recall that methods with default arguments are wrapped as if the equivalent overloaded methods had been parsed
|
|
(<a href="#SWIGPlus_default_args">Default arguments</a> section).
|
|
Let's consider the following example class:</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Spam {
|
|
public:
|
|
...
|
|
void bar(int i=-1, double d=0.0);
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The following <tt>%rename</tt> will match exactly and apply to all the target language overloaded methods because the declaration with the default arguments
|
|
exactly matches the wrapped method:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(newbar) Spam::bar(int i=-1, double d=0.0);
|
|
</pre>
|
|
</div>
|
|
|
|
<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:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(newbar) Spam::bar(int i, double d);
|
|
</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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(bar_2args) Spam::bar(int i, double d);
|
|
%rename(bar_1arg) Spam::bar(int i);
|
|
%rename(bar_default) Spam::bar();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Similarly, the extra overloaded methods can be selectively ignored using <tt>%ignore</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Compatibility note:</b> The <tt>%rename</tt> directive introduced the default argument matching rules in SWIG-1.3.23 at the same time as the changes
|
|
to wrapping methods with default arguments was introduced.
|
|
</p>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
<H3><a name="SWIGPlus_nn27">6.15.4 Comments on overloading</a></H3>
|
|
|
|
|
|
<p>
|
|
Support for overloaded methods was first added in SWIG-1.3.14. The implementation
|
|
is somewhat unusual when compared to similar tools. For instance, the order in which
|
|
declarations appear is largely irrelevant in SWIG. Furthermore, SWIG does not rely
|
|
upon trial execution or exception handling to figure out which method to invoke.
|
|
</p>
|
|
|
|
<p>
|
|
Internally, the overloading mechanism is completely configurable by the target language
|
|
module. Therefore, the degree of overloading support may vary from language to language.
|
|
As a general rule, statically typed languages like Java are able to provide more support
|
|
than dynamically typed languages like Perl, Python, Ruby, and Tcl.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_nn28">6.16 Overloaded operators</a></H2>
|
|
|
|
|
|
<p>
|
|
C++ overloaded operator declarations can be wrapped.
|
|
For example, consider a class like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Complex {
|
|
private:
|
|
double rpart, ipart;
|
|
public:
|
|
Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
|
|
Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
|
|
Complex &operator=(const Complex &c) {
|
|
rpart = c.rpart;
|
|
ipart = c.ipart;
|
|
return *this;
|
|
}
|
|
Complex operator+(const Complex &c) const {
|
|
return Complex(rpart+c.rpart, ipart+c.ipart);
|
|
}
|
|
Complex operator-(const Complex &c) const {
|
|
return Complex(rpart-c.rpart, ipart-c.ipart);
|
|
}
|
|
Complex operator*(const Complex &c) const {
|
|
return Complex(rpart*c.rpart - ipart*c.ipart,
|
|
rpart*c.ipart + c.rpart*ipart);
|
|
}
|
|
Complex operator-() const {
|
|
return Complex(-rpart, -ipart);
|
|
}
|
|
double re() const { return rpart; }
|
|
double im() const { return ipart; }
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When operator declarations appear, they are handled in
|
|
<em>exactly</em> the same manner as regular methods. However, the
|
|
names of these methods are set to strings like "<tt>operator +</tt>"
|
|
or "<tt>operator -</tt>". The problem with these names is that they
|
|
are illegal identifiers in most scripting languages. For instance,
|
|
you can't just create a method called "<tt>operator +</tt>" in
|
|
Python--there won't be any way to call it.
|
|
</p>
|
|
|
|
<p>
|
|
Some language modules already know how to automatically handle certain
|
|
operators (mapping them into operators in the target language).
|
|
However, the underlying implementation of this is really managed in a
|
|
very general way using the <tt>%rename</tt> directive. For example,
|
|
in Python a declaration similar to this is used:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(__add__) Complex::operator+;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
This binds the + operator to a method called <tt>__add__</tt> (which
|
|
is conveniently the same name used to implement the Python + operator).
|
|
Internally, the generated wrapper code for a wrapped operator will look
|
|
something like this pseudocode:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
_wrap_Complex___add__(args) {
|
|
... get args ...
|
|
obj->operator+(args);
|
|
...
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When used in the target language, it may now be possible to use the overloaded
|
|
operator normally. For example:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
>>> a = Complex(3, 4)
|
|
>>> b = Complex(5, 2)
|
|
>>> c = a + b # Invokes __add__ method
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
It is important to realize that there is nothing magical happening
|
|
here. The <tt>%rename</tt> directive really only picks a valid method
|
|
name. If you wrote this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(add) operator+;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The resulting scripting interface might work like this:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
a = Complex(3, 4)
|
|
b = Complex(5, 2)
|
|
c = a.add(b) # Call a.operator+(b)
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
All of the techniques described to deal with overloaded functions also
|
|
apply to operators. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%ignore Complex::operator=; // Ignore = in class Complex
|
|
%ignore *::operator=; // Ignore = in all classes
|
|
%ignore operator=; // Ignore = everywhere.
|
|
|
|
%rename(__sub__) Complex::operator-;
|
|
%rename(__neg__) Complex::operator-(); // Unary -
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The last part of this example illustrates how multiple definitions of
|
|
the <tt>operator-</tt> method might be handled.
|
|
</p>
|
|
|
|
<p>
|
|
Handling operators in this manner is mostly straightforward. However, there are a few subtle
|
|
issues to keep in mind:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><p>In C++, it is fairly common to define different versions of the operators to account for
|
|
different types. For example, a class might also include a friend function like this:</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Complex {
|
|
public:
|
|
friend Complex operator+(Complex &, double);
|
|
};
|
|
Complex operator+(Complex &, double);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
SWIG simply ignores all <tt>friend</tt> declarations. Furthermore, it
|
|
doesn't know how to associate the associated <tt>operator+</tt> with
|
|
the class (because it's not a member of the class).
|
|
</p>
|
|
|
|
<p>
|
|
It's still possible to make a wrapper for this operator, but you'll
|
|
have to handle it like a normal function. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(add_complex_double) operator+(Complex &, double);
|
|
</pre>
|
|
</div>
|
|
</li>
|
|
|
|
<li><p>Certain operators are ignored by default. For instance, <tt>new</tt> and <tt>delete</tt> operators
|
|
are ignored as well as conversion and index operators. A warning such as the one below is shown:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:12: Warning 503: Can't wrap 'operator []' unless renamed to a valid identifier.
|
|
</pre>
|
|
</div>
|
|
</li>
|
|
|
|
<li><p>The index operator, <tt>operator[]</tt>, is particularly difficult to overload due to differences in C++
|
|
implementations. Specifically, the get and set operators in other languages typically are separated
|
|
into two methods such that additional logic can be packed into the operations; C# uses
|
|
<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 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>
|
|
</li>
|
|
|
|
<li>The semantics of certain C++ operators may not match those in the target language.
|
|
</li>
|
|
</ul>
|
|
|
|
<H2><a name="SWIGPlus_class_extension">6.17 Class extension</a></H2>
|
|
|
|
|
|
<p>
|
|
New methods can be added to a class using the <tt>%extend</tt>
|
|
directive. This directive is primarily used in conjunction with proxy
|
|
classes to add additional functionality to an existing class. For
|
|
example :
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module vector
|
|
%{
|
|
#include "vector.h"
|
|
%}
|
|
|
|
class Vector {
|
|
public:
|
|
double x, y, z;
|
|
Vector();
|
|
~Vector();
|
|
... bunch of C++ methods ...
|
|
%extend {
|
|
char *__str__() {
|
|
static char temp[256];
|
|
sprintf(temp, "[ %g, %g, %g ]", $self->x, $self->y, $self->z);
|
|
return &temp[0];
|
|
}
|
|
}
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
This code adds a <tt>__str__</tt> method to our class for producing a
|
|
string representation of the object. In Python, such a method would
|
|
allow us to print the value of an object using the <tt>print</tt>
|
|
command.
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
>>>
|
|
>>> v = Vector();
|
|
>>> v.x = 3
|
|
>>> v.y = 4
|
|
>>> v.z = 0
|
|
>>> print(v)
|
|
[ 3.0, 4.0, 0.0 ]
|
|
>>>
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
The C++ 'this' pointer is often needed to access member variables, methods etc.
|
|
The <tt>$self</tt> special variable should be used wherever you could use 'this'.
|
|
The example above demonstrates this for accessing member variables.
|
|
Note that the members dereferenced by <tt>$self</tt> must be public members as the code is ultimately generated
|
|
into a global function and so will not have any access to non-public members.
|
|
The implicit 'this' pointer that is present in C++ methods is not present in <tt>%extend</tt> methods.
|
|
In order to access anything in the extended class or its base class, an explicit 'this' is required.
|
|
The following example shows how one could access base class members:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
struct Base {
|
|
virtual void method(int v) {
|
|
...
|
|
}
|
|
int value;
|
|
};
|
|
struct Derived : Base {
|
|
};
|
|
%extend Derived {
|
|
virtual void method(int v) {
|
|
$self->Base::method(v); // akin to this->Base::method(v);
|
|
$self->value = v; // akin to this->value = v;
|
|
...
|
|
}
|
|
}
|
|
</pre></div>
|
|
|
|
<p>
|
|
The following special variables are expanded if used within a %extend block:
|
|
$name, $symname, $overname, $decl, $fulldecl, $parentclassname and $parentclasssymname.
|
|
The <a href="Customization.html#Customization_exception_special_variables">Special variables</a> section provides more information each of these special variables.
|
|
</p>
|
|
|
|
<p>
|
|
The <tt>%extend</tt> directive follows all of the same conventions
|
|
as its use with C structures. Please refer to the <a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a>
|
|
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>
|
|
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>
|
|
|
|
|
|
<p>
|
|
Template type names may appear anywhere a type
|
|
is expected in an interface file. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void foo(vector<int> *a, int n);
|
|
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 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(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>
|
|
|
|
<p>
|
|
The type system is smart enough to figure out clever games
|
|
you might try to play with <tt>typedef</tt>. For instance, consider this code:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
typedef int Integer;
|
|
void foo(vector<int> *x, vector<Integer> *y);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this case, <tt>vector<Integer></tt> is exactly the same type
|
|
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>
|
|
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>,
|
|
<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>.
|
|
</p>
|
|
|
|
<p>
|
|
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;
|
|
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];
|
|
}
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
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>
|
|
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">
|
|
<pre>
|
|
%rename(intList) List<int>; // Rename to a suitable identifier
|
|
class List<int> {
|
|
private:
|
|
int *data;
|
|
int nitems;
|
|
int maxitems;
|
|
public:
|
|
List(int max);
|
|
~List();
|
|
void append(int obj);
|
|
int length();
|
|
int get(int n);
|
|
};
|
|
</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:
|
|
</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>
|
|
but if %template is used before the template definition, such as:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%template(intList) List<int>;
|
|
template<class T> class List { ... };
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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;
|
|
...
|
|
void foo(List<Integer> *x);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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 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>
|
|
|
|
<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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// Function template
|
|
template<class T> T max(T a, T b) { return a > b ? a : b; }
|
|
|
|
// Make some different versions of this function
|
|
%template(maxint) max<int>;
|
|
%template(maxdouble) max<double>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this case, <tt>maxint</tt> and <tt>maxdouble</tt> become unique names for specific
|
|
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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
template <typename T, int max=100> class vector {
|
|
...
|
|
};
|
|
|
|
%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. 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(vec) vector<double>; // OK
|
|
%template(vec100) vector<double, 100>; // Ignored
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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>
|
|
|
|
|
|
<p>
|
|
When a template is instantiated using <tt>%template</tt>, information
|
|
about that class is saved by SWIG and used elsewhere in the program.
|
|
For example, if you wrote code like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
...
|
|
%template(intList) List<int>;
|
|
...
|
|
class UltraList : public List<int> {
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
then SWIG knows that <tt>List<int></tt> was already wrapped as a class called
|
|
<tt>intList</tt> and arranges to handle the inheritance correctly. If, on the other hand,
|
|
nothing is known about <tt>List<int></tt>, you will get a warning message similar to this:
|
|
</p>
|
|
|
|
<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.
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
template<class T> class Foo {
|
|
...
|
|
};
|
|
|
|
template<class T> class Bar : public Foo<T> {
|
|
...
|
|
};
|
|
|
|
// Instantiate base classes first
|
|
%template(intFoo) Foo<int>;
|
|
%template(doubleFoo) Foo<double>;
|
|
|
|
// Now instantiate derived classes
|
|
%template(intBar) Bar<int>;
|
|
%template(doubleBar) Bar<double>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The order is important since SWIG uses the instantiation names to
|
|
properly set up the inheritance hierarchy in the resulting wrapper
|
|
code (and base classes need to be wrapped before derived classes).
|
|
Don't worry--if you get the order wrong, SWIG should generate a warning message.
|
|
</p>
|
|
|
|
<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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%define TEMPLATE_WRAP(prefix, T...)
|
|
%template(prefix ## Foo) Foo<T >;
|
|
%template(prefix ## Bar) Bar<T >;
|
|
...
|
|
%enddef
|
|
|
|
TEMPLATE_WRAP(int, int)
|
|
TEMPLATE_WRAP(double, double)
|
|
TEMPLATE_WRAP(String, char *)
|
|
TEMPLATE_WRAP(PairStringInt, std::pair<string, int>)
|
|
...
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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_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>
|
|
The SWIG template mechanism <em>does</em> support specialization. For instance, if you define
|
|
a class like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
template<> class List<int> {
|
|
private:
|
|
int *data;
|
|
int nitems;
|
|
int maxitems;
|
|
public:
|
|
List(int max);
|
|
~List();
|
|
void append(int obj);
|
|
int length();
|
|
int get(int n);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
then SWIG will use this code whenever the user expands <tt>List<int></tt>. In practice,
|
|
this may have very little effect on the underlying wrapper code since
|
|
specialization is often used to provide slightly modified method bodies (which
|
|
are ignored by SWIG). However, special SWIG
|
|
directives such as <tt>%typemap</tt>, <tt>%extend</tt>, and so forth can be attached
|
|
to a specialization to provide customization for specific types.
|
|
</p>
|
|
|
|
<p>
|
|
Partial template specialization is partially supported by SWIG. For example, this
|
|
code defines a template that is applied when the template argument is a pointer.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
template<class T> class List<T*> {
|
|
private:
|
|
T *data;
|
|
int nitems;
|
|
int maxitems;
|
|
public:
|
|
List(int max);
|
|
~List();
|
|
void append(T obj);
|
|
int length();
|
|
T get(int n);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
SWIG supports both template explicit specialization and partial specialization. Consider:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
template<class T1, class T2> class Foo { }; // (1) primary template
|
|
template<> class Foo<double *, int *> { }; // (2) explicit specialization
|
|
template<class T1, class T2> class Foo<T1, T2 *> { }; // (3) partial specialization
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
SWIG is able to properly match explicit instantiations:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
<tt>Foo<double *, int *></tt> // explicit specialization matching (2)
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
SWIG implements template argument deduction so that the following partial specialization examples work just like they would with a C++ compiler:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
<tt>Foo<int *, int *></tt> // partial specialization matching (3)
|
|
<tt>Foo<int *, const int *></tt> // partial specialization matching (3)
|
|
<tt>Foo<int *, int **></tt> // partial specialization matching (3)
|
|
</pre>
|
|
</div>
|
|
|
|
<H3><a name="SWIGPlus_template_member">6.18.7 Member templates</a></H3>
|
|
|
|
|
|
<p>
|
|
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 function template might
|
|
look like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
template<class T> void bar(T x, T y) { ... };
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
To expand the template, simply use <tt>%template</tt> inside the class.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
template<class T> void bar(T x, T y) { ... };
|
|
...
|
|
%template(barint) bar<int>;
|
|
%template(bardouble) bar<double>;
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Or, if you want to leave the original class definition alone, just do this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
template<class T> void bar(T x, T y) { ... };
|
|
...
|
|
};
|
|
...
|
|
%extend Foo {
|
|
%template(barint) bar<int>;
|
|
%template(bardouble) bar<double>;
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
or simply
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
template<class T> void bar(T x, T y) { ... };
|
|
...
|
|
};
|
|
...
|
|
|
|
%template(bari) Foo::bar<int>;
|
|
%template(bard) Foo::bar<double>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this case, the <tt>%extend</tt> directive is not needed, and
|
|
<tt>%template</tt> does exactly the same job, i.e., it adds two new
|
|
methods to the Foo class.
|
|
</p>
|
|
|
|
|
|
<p>
|
|
Now, if your target language supports overloading, you can even try
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%template(bar) Foo::bar<int>;
|
|
%template(bar) Foo::bar<double>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
and since the two new wrapped methods have the same name 'bar', they will be
|
|
overloaded, and when called, the correct method will be dispatched
|
|
depending on the argument type.
|
|
</p>
|
|
|
|
|
|
<p>
|
|
When used with members, the <tt>%template</tt> directive may be placed in another
|
|
class template. Here is a slightly perverse example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// A template
|
|
template<class T> class Foo {
|
|
public:
|
|
// A member template
|
|
template<class S> T bar(S x, S y) { ... };
|
|
...
|
|
};
|
|
|
|
// Expand a few member templates
|
|
%extend Foo {
|
|
%template(bari) bar<int>;
|
|
%template(bard) bar<double>;
|
|
}
|
|
|
|
// Create some wrappers for the template
|
|
%template(Fooi) Foo<int>;
|
|
%template(Food) Foo<double>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Miraculously, you will find that each expansion of <tt>Foo</tt> has member
|
|
functions <tt>bari()</tt> and <tt>bard()</tt> added.
|
|
</p>
|
|
|
|
<p>
|
|
A common use of member templates is to define constructors for copies
|
|
and conversions. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
template<class T1, class T2> struct pair {
|
|
T1 first;
|
|
T2 second;
|
|
pair() : first(T1()), second(T2()) { }
|
|
pair(const T1 &x, const T2 &y) : first(x), second(y) { }
|
|
template<class U1, class U2> pair(const pair<U1, U2> &x)
|
|
: first(x.first), second(x.second) { }
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<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 class template itself. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%extend pair {
|
|
%template(pair) pair<T1, T2>; // Generate default copy constructor
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When using <tt>%extend</tt> in this manner, notice how you can still use the template parameters in
|
|
the original template definition.
|
|
</p>
|
|
|
|
<p>
|
|
Alternatively, you could expand the constructor template in selected instantiations. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// Instantiate a few versions
|
|
%template(pairii) pair<int, int>;
|
|
%template(pairdd) pair<double, double>;
|
|
|
|
// Create a default constructor only
|
|
%extend pair<int, int> {
|
|
%template(paird) pair<int, int>; // Default constructor
|
|
};
|
|
|
|
// Create default and conversion constructors
|
|
%extend pair<double, double> {
|
|
%template(paird) pair<double, double>; // Default constructor
|
|
%template(pairc) pair<int, int>; // Conversion constructor
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
|
|
<p>And if your target language supports overloading, then you can try
|
|
instead:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// Create default and conversion constructors
|
|
%extend pair<double, double> {
|
|
%template(pair) pair<double, double>; // Default constructor
|
|
%template(pair) pair<int, int>; // Conversion constructor
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this case, the default and conversion constructors have the same
|
|
name. Hence, SWIG will overload them and define an unique visible
|
|
constructor, that will dispatch the proper call depending on the argument
|
|
type.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_template_scoping">6.18.8 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.9 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
|
|
<tt>%rename</tt>, <tt>%extend</tt>, and <tt>%typemap</tt> can be
|
|
included directly in template definitions. For example:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
// File : list.h
|
|
template<class T> class List {
|
|
...
|
|
public:
|
|
%rename(__getitem__) get(int);
|
|
List(int max);
|
|
~List();
|
|
...
|
|
T get(int index);
|
|
%extend {
|
|
char *__str__() {
|
|
/* Make a string representation */
|
|
...
|
|
}
|
|
}
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
In this example, the extra SWIG directives are propagated to <em>every</em> template
|
|
instantiation.
|
|
</p>
|
|
|
|
<p>
|
|
It is also possible to separate these declarations from the class template. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(__getitem__) List::get;
|
|
%extend List {
|
|
char *__str__() {
|
|
/* Make a string representation */
|
|
...
|
|
}
|
|
/* Make a copy */
|
|
T *__copy__() {
|
|
return new List<T>(*$self);
|
|
}
|
|
};
|
|
|
|
...
|
|
template<class T> class List {
|
|
...
|
|
public:
|
|
List() { }
|
|
T get(int index);
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When <tt>%extend</tt> is decoupled from the class definition, it is
|
|
legal to use the same template parameters as provided in the class definition.
|
|
These are replaced when the template is expanded.
|
|
In addition, the <tt>%extend</tt> directive can be used to add
|
|
additional methods to a specific instantiation. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%template(intList) List<int>;
|
|
|
|
%extend List<int> {
|
|
void blah() {
|
|
printf("Hey, I'm an List<int>!\n");
|
|
}
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
It is even possible to extend a class via <tt>%extend</tt> with template methods, for example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <std_string.i>
|
|
|
|
%inline %{
|
|
class ExtendMe {
|
|
public:
|
|
template <typename T>
|
|
T do_stuff_impl(int a, T b, double d) {
|
|
return b;
|
|
}
|
|
};
|
|
%}
|
|
|
|
%extend ExtendMe {
|
|
template<typename T>
|
|
T do_overloaded_stuff(T b) {
|
|
return $self->do_stuff_impl(0, b, 4.0);
|
|
}
|
|
}
|
|
%template(do_overloaded_stuff) ExtendMe::do_overloaded_stuff<std::string>;
|
|
%template(do_overloaded_stuff) ExtendMe::do_overloaded_stuff<double>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The wrapped <tt>ExtendMe</tt> class will then have two (overloaded) methods called <tt>do_overloaded_stuff</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Compatibility Note</b>: Extending a class with template methods was added in version 3.0.12
|
|
</p>
|
|
|
|
<p>
|
|
Needless to say, SWIG's template support provides plenty of opportunities to
|
|
break the universe. That said, an important final point is that <b>SWIG does
|
|
not perform extensive error checking of templates!</b> Specifically, SWIG does
|
|
not perform type checking nor does it check to see if the actual contents of the
|
|
template declaration make any sense. Since the C++ compiler checks this when it
|
|
compiles the resulting wrapper file, there is no practical reason for SWIG to
|
|
duplicate this functionality.
|
|
</p>
|
|
|
|
<a name="SWIGPlus_template_nested_class_example"></a>
|
|
<p>
|
|
As SWIG's template support does not perform type checking <tt>%template</tt>
|
|
can be used as early as after a template declaration. You can, and rarely have
|
|
to, use <tt>%template</tt> before the template parameters have been declared.
|
|
For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
template <class T> class OuterTemplateClass {};
|
|
|
|
// 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>
|
|
|
|
|
|
// 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;
|
|
};
|
|
|
|
struct OuterClass::InnerStruct {};
|
|
|
|
// Expanding the template at this point with %template is too late as the
|
|
// OuterClass::InnerClass declaration is processed inside OuterClass.
|
|
|
|
class OuterClass::InnerClass : public OuterTemplateClass<InnerStruct> {};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Compatibility Note</b>: The first implementation of template support relied heavily on
|
|
macro expansion in the preprocessor. Templates have been more tightly integrated into
|
|
the parser and type system in SWIG-1.3.12 and the preprocessor is no longer used. Code
|
|
that relied on preprocessing features in template expansion will no longer work. However,
|
|
SWIG still allows the # operator to be used to generate a string from a template argument.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Compatibility Note</b>: In earlier versions of SWIG, the <tt>%template</tt> directive
|
|
introduced a new class name. This name could then be used with other directives. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%template(vectori) vector<int>;
|
|
%extend vectori {
|
|
void somemethod() { }
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
This behavior is no longer supported. Instead, you should use the original template name
|
|
as the class name. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%template(vectori) vector<int>;
|
|
%extend vector<int> {
|
|
void somemethod() { }
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Similar changes apply to typemaps and other customization features.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_namespaces">6.19 Namespaces</a></H2>
|
|
|
|
|
|
<p>
|
|
Support for C++ namespaces is comprehensive, but by default simple, however,
|
|
some target languages can turn on more advanced namespace support via the
|
|
<a href="#SWIGPlus_nspace">nspace feature</a>, described later.
|
|
Code within unnamed namespaces is ignored as there is no external
|
|
access to symbols declared within the unnamed namespace.
|
|
Before detailing the default implementation for named namespaces,
|
|
it is worth noting that the semantics of C++ namespaces is extremely
|
|
non-trivial--especially with regard to the C++ type system and class
|
|
machinery. At a most basic level, namespaces are sometimes used to
|
|
encapsulate common functionality. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace math {
|
|
double sin(double);
|
|
double cos(double);
|
|
|
|
class Complex {
|
|
double im, re;
|
|
public:
|
|
...
|
|
};
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Members of the namespace are accessed in C++ by prepending the namespace prefix
|
|
to names. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
double x = math::sin(1.0);
|
|
double magnitude(math::Complex *c);
|
|
math::Complex c;
|
|
...
|
|
</pre>
|
|
</div>
|
|
|
|
<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 a <tt>using</tt> declaration:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
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 via a <tt>using</tt> directive:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
using namespace math; // Using directive
|
|
double x = sin(1.0);
|
|
double magnitude(Complex *c);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Alternatively, a namespace can be aliased:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace M = math;
|
|
double x = M::sin(1.0);
|
|
double magnitude(M::Complex *c);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Using combinations of these features, it is possible to write head-exploding code like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace A {
|
|
class Foo {
|
|
};
|
|
}
|
|
|
|
namespace B {
|
|
namespace C {
|
|
using namespace A;
|
|
}
|
|
typedef C::Foo FooClass;
|
|
}
|
|
|
|
namespace BIGB = B;
|
|
|
|
namespace D {
|
|
using BIGB::FooClass;
|
|
class Bar : public FooClass {
|
|
}
|
|
};
|
|
|
|
class Spam : public D::Bar {
|
|
};
|
|
|
|
void evil(A::Foo *a, B::FooClass *b, B::C::Foo *c, BIGB::FooClass *d,
|
|
BIGB::C::Foo *e, D::FooClass *f);
|
|
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Given the possibility for such perversion, it's hard to imagine how
|
|
every C++ programmer might want such code wrapped into the target
|
|
language. Clearly this code defines three different classes. However, one
|
|
of those classes is accessible under at least six different names!
|
|
</p>
|
|
|
|
<p>
|
|
SWIG fully supports C++ namespaces in its internal type system and
|
|
class handling code. If you feed SWIG the above code, it will be
|
|
parsed correctly, it will generate compilable wrapper code, and it
|
|
will produce a working scripting language module. However, the
|
|
default wrapping behavior is to flatten namespaces in the target
|
|
language. This means that the contents of all namespaces are merged
|
|
together in the resulting scripting language module. For example, if
|
|
you have code like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%module foo
|
|
namespace foo {
|
|
void bar(int);
|
|
void spam();
|
|
}
|
|
|
|
namespace bar {
|
|
void blah();
|
|
}
|
|
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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>
|
|
There is some rationale for taking this approach. Since C++
|
|
namespaces are often used to define modules in C++, there is a natural
|
|
correlation between the likely contents of a SWIG module and the contents of
|
|
a namespace. For instance, it would not be unreasonable to assume
|
|
that a programmer might make a separate extension module for each C++
|
|
namespace. In this case, it would be redundant to prepend everything
|
|
with an additional namespace prefix when the module itself already
|
|
serves as a namespace in the target language. Or put another way, if
|
|
you want SWIG to keep namespaces separate, simply wrap each namespace with its
|
|
own SWIG interface.
|
|
</p>
|
|
|
|
<p>
|
|
Because namespaces are flattened, it is possible for symbols defined in different
|
|
namespaces to generate a name conflict in the target language. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace A {
|
|
void foo(int);
|
|
}
|
|
namespace B {
|
|
void foo(double);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When this conflict occurs, you will get an error message that resembles this:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:26: Error: 'foo' is multiply defined in the generated target language module.
|
|
example.i:23: Error: Previous declaration of 'foo'
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
To resolve this error, simply use <tt>%rename</tt> to disambiguate the declarations. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(B_foo) B::foo;
|
|
...
|
|
namespace A {
|
|
void foo(int);
|
|
}
|
|
namespace B {
|
|
void foo(double); // Gets renamed to B_foo
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Similarly, <tt>%ignore</tt> can be used to ignore declarations.
|
|
</p>
|
|
|
|
<p>
|
|
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>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace A {
|
|
typedef int Integer;
|
|
}
|
|
using namespace A;
|
|
void foo(Integer x);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
SWIG knows that <tt>Integer</tt> is the same as <tt>A::Integer</tt> which
|
|
is the same as <tt>int</tt>.
|
|
</p>
|
|
|
|
<P>
|
|
Namespaces may be combined with templates. If necessary, the
|
|
<tt>%template</tt> directive can be used to expand a template defined
|
|
in a different namespace. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace foo {
|
|
template<typename T> T max(T a, T b) { return a > b ? a : b; }
|
|
}
|
|
|
|
using foo::max;
|
|
|
|
%template(maxint) max<int>; // Okay.
|
|
%template(maxfloat) foo::max<float>; // Okay (qualified name).
|
|
|
|
namespace bar {
|
|
using namespace foo;
|
|
%template(maxdouble) max<double>; // Okay.
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The combination of namespaces and other SWIG directives may introduce subtle scope-related problems.
|
|
The key thing to keep in mind is that all SWIG generated wrappers are produced
|
|
in the <em>global</em> namespace. Symbols from other namespaces are always accessed using fully
|
|
qualified names---names are never imported into the global space unless the interface happens to
|
|
do so with a <tt>using</tt> declaration. In almost all cases, SWIG adjusts typenames and symbols
|
|
to be fully qualified. However, this is not done in code fragments such as function bodies,
|
|
typemaps, exception handlers, and so forth. For example, consider the following:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace foo {
|
|
typedef int Integer;
|
|
class bar {
|
|
public:
|
|
...
|
|
};
|
|
}
|
|
|
|
%extend foo::bar {
|
|
Integer add(Integer x, Integer y) {
|
|
Integer r = x + y; // Error. Integer not defined in this scope
|
|
return r;
|
|
}
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this case, SWIG correctly resolves the added method parameters and return type to
|
|
<tt>foo::Integer</tt>. However, since function bodies aren't parsed and such code is
|
|
emitted in the global namespace, this code produces a compiler error about <tt>Integer</tt>.
|
|
To fix the problem, make sure you use fully qualified names. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%extend foo::bar {
|
|
Integer add(Integer x, Integer y) {
|
|
foo::Integer r = x + y; // Ok.
|
|
return r;
|
|
}
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Note:</b> SWIG does <em>not</em> propagate <tt>using</tt> declarations to
|
|
the resulting wrapper code. If these declarations appear in an interface,
|
|
they should <em>also</em> appear in any header files that might have been
|
|
included in a <tt>%{ ... %}</tt> section. In other words, don't insert extra
|
|
<tt>using</tt> declarations into a SWIG interface unless they also appear
|
|
in the underlying C++ code.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> Code inclusion directives such as <tt>%{ ... %}</tt> or
|
|
<tt>%inline %{ ... %}</tt> should not be placed inside a namespace declaration.
|
|
The code emitted by these directives will not be enclosed in a namespace and
|
|
you may get very strange results. If you need to use namespaces with
|
|
these directives, consider the following:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// Good version
|
|
%inline %{
|
|
namespace foo {
|
|
void bar(int) { ... }
|
|
...
|
|
}
|
|
%}
|
|
|
|
// Bad version. Emitted code not placed in namespace.
|
|
namespace foo {
|
|
%inline %{
|
|
void bar(int) { ... } /* I'm bad */
|
|
...
|
|
%}
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Note:</b> When the <tt>%extend</tt> directive is used inside a namespace, the namespace name is
|
|
included in the generated functions. For example, if you have code like this,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace foo {
|
|
class bar {
|
|
public:
|
|
%extend {
|
|
int blah(int x);
|
|
};
|
|
};
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
the added method <tt>blah()</tt> is mapped to a function <tt>int foo_bar_blah(foo::bar *self, int x)</tt>.
|
|
This function resides in the global namespace.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> Although namespaces are flattened in the target language, the SWIG generated wrapper
|
|
code observes the same namespace conventions as used in the input file. Thus, if there are no symbol
|
|
conflicts in the input, there will be no conflicts in the generated code.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> In the same way that no resolution is performed on parameters, a conversion operator name must match exactly to how it is defined. Do not change the qualification of the operator. For example, suppose you had an interface like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace foo {
|
|
class bar;
|
|
class spam {
|
|
public:
|
|
...
|
|
operator bar(); // Conversion of spam -> bar
|
|
...
|
|
};
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The following is how the feature is expected to be written for a successful match:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(tofoo) foo::spam::operator bar();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The following does not work as no namespace resolution is performed in the matching of conversion operator names:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(tofoo) foo::spam::operator <b>foo::</b>bar();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Note, however, that if the operator is defined using a qualifier in its name, then the feature must use it too...
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename(tofoo) foo::spam::operator bar(); // will not match
|
|
%rename(tofoo) foo::spam::operator foo::bar(); // will match
|
|
namespace foo {
|
|
class bar;
|
|
class spam {
|
|
public:
|
|
...
|
|
operator foo::bar();
|
|
...
|
|
};
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Compatibility Note:</b> Versions of SWIG prior to 1.3.32 were inconsistent in this approach. A fully qualified name was usually required, but would not work in some situations.
|
|
</p>
|
|
|
|
|
|
<p>
|
|
<b>Note:</b> The flattening of namespaces is only intended to serve as
|
|
a basic namespace implementation.
|
|
More advanced handling of namespaces is discussed next.
|
|
</p>
|
|
|
|
<H3><a name="SWIGPlus_nspace">6.19.1 The nspace feature for namespaces</a></H3>
|
|
|
|
|
|
<p>
|
|
The <tt>nspace</tt> feature operates in two modes.
|
|
Firstly, in a simple enable/disable mode to mirror the C++ namespaces into the target language specific concept of a C++ namespace.
|
|
Secondly, a complex mode for modifying, renaming or moving the hierarchies of the language specific concept of a C++ namespace.
|
|
</p>
|
|
|
|
<p>
|
|
The types of symbols that the feature can be applied to are any class, struct, union or enum declared within a named namespace.
|
|
This also includes templates of the aforementioned types.
|
|
The feature wraps the type within the target language specific concept of a namespace,
|
|
such as a Java package or C# namespace.
|
|
Only some target languages provide support for the <tt>nspace</tt> feature.
|
|
Please see the target language specific sections to see if the language you are interested in supports the nspace feature.
|
|
</p>
|
|
|
|
<H4><a name="SWIGPlus_nspace_feature_flag">6.19.1.1 %nspace for mirroring namespace hierarchies</a></H4>
|
|
|
|
|
|
<p>
|
|
In this simple mode the <tt>nspace</tt> feature works as a <a href="Customization.html#Customization_feature_flags">feature flag</a> to enable or disable the feature for a given C++ symbol.
|
|
As described earlier, all namespace are flattened by default, hence the <tt>nspace</tt> feature is disabled by default.
|
|
When the feature is enabled, the C++ namespace hierarchies are mirrored into the target language concept of a namespace.
|
|
</p>
|
|
|
|
<p>
|
|
The feature flag is demonstrated below using the following example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%feature("nspace") MyWorld::Material::Color;
|
|
%nspace MyWorld::Wrapping::Color; // %nspace is a macro for %feature("nspace")
|
|
|
|
namespace MyWorld {
|
|
namespace Material {
|
|
class Color {
|
|
...
|
|
};
|
|
}
|
|
namespace Wrapping {
|
|
class Color {
|
|
...
|
|
};
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
By default, without the above <tt>nspace</tt> feature flags (or an appropriate <tt>%rename</tt>), SWIG outputs the following warning resulting in just one of the <tt>Color</tt> classes being available for use from the target language:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:9: Error: 'Color' is multiply defined in the generated target language module.
|
|
example.i:5: Error: Previous declaration of 'Color'
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Let's consider C# as the target language.
|
|
With the two <tt>nspace</tt> feature flags, the two C# <tt>Color</tt> proxy classes are generated into the equivalent C# namespaces that mirror the C++ namespace hierarchies.
|
|
A fully qualified constructor call of each these two types in C# is then:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
var materialColor = new MyWorld.Material.Color();
|
|
var wrappingColor = new MyWorld.Wrapping.Color();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Without the <tt>nspace</tt> feature flag, no namespaces are available in C# and the fully qualified constructor call of the type in C# would simply be:
|
|
</p>
|
|
<div class="targetlang">
|
|
<pre>
|
|
var materialColor = new Color();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Note that the <tt>nspace</tt> feature does not apply to variables and functions simply declared in a namespace. For example, the following symbols cannot co-exist in the target language without renaming. This may change in a future version.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace MyWorld {
|
|
namespace Material {
|
|
int quantity;
|
|
void dispatch();
|
|
}
|
|
namespace Wrapping {
|
|
int quantity;
|
|
void dispatch();
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Compatibility Note:</b> The simple <tt>%nspace</tt> feature flag was first introduced in SWIG-2.0.0.
|
|
</p>
|
|
|
|
<H4><a name="SWIGPlus_nspacemove">6.19.1.2 %nspacemove for modifying namespace hierarchies</a></H4>
|
|
|
|
|
|
<p>
|
|
The more complex mode for <tt>nspace</tt> provides the ability to move a type into a differently named target language equivalent of a namespace.
|
|
This allows a fully flexible approach to mapping C++ namespaces into a target language equivalent of a namespace, such as:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> Renaming a namespace.</li>
|
|
<li> Renaming any number of sub-namespaces of a namespace.</li>
|
|
<li> Moving a type to a completely different namespace.</li>
|
|
<li> Splitting many types in one namespace into multiple different namespaces.</li>
|
|
<li> Adding nested sub-namespaces to a namespace.</li>
|
|
<li> Removing nested sub-namespaces of namespace.</li>
|
|
<li> Combinations of the above.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The <tt>nspace</tt> feature attaches to a C++ symbol and provides a target language namespace for that symbol to move to.
|
|
The <tt>%nspacemove</tt> directive is a macro for the <tt>nspace</tt> feature as follows:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
#define %nspacemove(NAMESPACE) %feature("nspace", #NAMESPACE)
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
where the target namespace is provided in <tt>NAMESPACE</tt> and is specified in valid C++ syntax, such as <tt>A::B::C</tt>.
|
|
Internally, SWIG converts the C++ namespace into a target language equivalent,
|
|
so this might for example, result in a C# namespace called <tt>A.B.C</tt> or a Java package named <tt>A.B.C</tt>.
|
|
Note that the target namespace does not have to actually exist in any of the C++ code that SWIG parses; it could be entirely made-up.
|
|
</p>
|
|
|
|
<p>
|
|
Either the <tt>%nspacemove</tt> macro or the more verbose <tt>%feature</tt> syntax can be used. Please see the <a href="Customization.html#Customization_features">Features and the %feature directive</a> section for more details of SWIG features.
|
|
</p>
|
|
|
|
<p>
|
|
An example follows:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// Enable the nspace feature flag for all symbols
|
|
%nspace;
|
|
|
|
// Override the nspace feature for a subset of symbols by moving them into different namespaces
|
|
%nspacemove(A) A::B::C::Struct1;
|
|
%feature("nspace", "A::B::X") A::B::C::Struct2;
|
|
%nspacemove(A::B::C::D) A::B::C::Struct4;
|
|
%nspacemove(Somewhere::Else) A::B::C::Struct5;
|
|
|
|
%inline %{
|
|
namespace A {
|
|
namespace B {
|
|
namespace C {
|
|
struct Struct1 {
|
|
// ...
|
|
};
|
|
struct Struct2 {
|
|
// ...
|
|
};
|
|
struct Struct3 {
|
|
// ...
|
|
};
|
|
struct Struct4 {
|
|
// ...
|
|
};
|
|
struct Struct5 {
|
|
// ...
|
|
};
|
|
}
|
|
}
|
|
}
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The C# code below constructs each of the above classes.
|
|
It shows the namespaces that the C# proxy classes have been moved into,
|
|
noting though that <tt>Struct4</tt> merely exactly mirrors the C++ namespace hierarchy as it has the <tt>nspace</tt> feature flag attached to it.
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
var s1 = new A.Struct1();
|
|
var s2 = new A.B.X.Struct2();
|
|
var s3 = new A.B.C.Struct3();
|
|
var s4 = new A.B.C.D.Struct4();
|
|
var s5 = new Somewhere.Else.Struct5();
|
|
</pre>
|
|
</div>
|
|
|
|
<H4><a name="SWIGPlus_nspace_more">6.19.1.3 More about the nspace feature</a></H4>
|
|
|
|
|
|
<p>
|
|
When the <tt>nspace</tt> feature is attached to a class or enum, all contained symbols (members) are also automatically moved into the target language namespace.
|
|
Contained symbols include all enum values, static and non-static class members as well as nested classes.
|
|
There is no need for additional <tt>nspace</tt> features to be specified for all the contained symbols.
|
|
Below is an example showing this.
|
|
It also shows the nspace feature working for templates.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// Easy way to move all the Structure template instantiations into a different namespace
|
|
%nspacemove(A::Different::Space) Space::Structure;
|
|
|
|
%inline %{
|
|
namespace Space {
|
|
template<typename T>
|
|
struct Structure {
|
|
static int Count;
|
|
static void StaticMethod(T t) {
|
|
// ...
|
|
}
|
|
struct NestedStruct {
|
|
// ...
|
|
};
|
|
};
|
|
template<typename T>
|
|
int Structure<T>::Count = 0;
|
|
}
|
|
%}
|
|
%template(StructureInt) Space::Structure<int>;
|
|
%template(StructureString) Space::Structure<const char *>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The C# code below shows the full C# namespace <tt>A.Different.Space</tt> being used as one would expect for all the contained symbols within a C# class.
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
var s = new A.Different.Space.StructureInt();
|
|
int count = A.Different.Space.StructureInt.Count;
|
|
var n = new A.Different.Space.StructureInt.NestedStruct();
|
|
A.Different.Space.StructureInt.StaticMethod(99);
|
|
A.Different.Space.StructureString.StaticMethod("hi");
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Any attempt to give a different namespace value to a nested class or enum will issue a warning.
|
|
For example, adding the following to the above in an attempt to move one of the instantiated nested classes into another namespace like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%nspacemove(Bad::Space) Space::Structure<int>::NestedStruct;
|
|
... rest of example above ...
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
will result in the following warning:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
Warning 406: Ignoring nspace setting (Bad::Space) for 'Space::Structure< int >::NestedStruct',
|
|
Warning 406: as it conflicts with the nspace setting (A::Different::Space) for outer class 'Space::Structure< int >'.
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Compatibility Note:</b> Modifying namespace hierarchies via <tt>%nspacemove</tt> was first introduced in SWIG-4.3.0.
|
|
</p>
|
|
|
|
|
|
|
|
<H2><a name="SWIGPlus_renaming_templated_types_namespaces">6.20 Renaming templated types in namespaces</a></H2>
|
|
|
|
|
|
<p>
|
|
As has been mentioned, when %rename includes parameters, the parameter types must match exactly (no typedef or namespace resolution is performed).
|
|
SWIG treats templated types slightly differently and has an additional matching rule so unlike non-templated types, an exact match is not always required.
|
|
If the fully qualified templated type is specified, it will have a higher precedence over the generic template type.
|
|
In the example below, the generic template type is used to rename to <tt>bbb</tt> and the fully qualified type is used to rename to <tt>ccc</tt>.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%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
|
|
|
|
namespace Space {
|
|
class XYZ {};
|
|
template<typename T> struct ABC {
|
|
void aaa(T t) {}
|
|
};
|
|
}
|
|
%template(ABCXYZ) Space::ABC<Space::XYZ>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
It should now be apparent that there are many ways to achieve a renaming with %rename. This is demonstrated
|
|
by the following two examples, which are effectively the same as the above example.
|
|
Below shows how %rename can be placed inside a namespace.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace Space {
|
|
%rename(bbb) ABC::aaa(T t); // will match but with lower precedence than ccc
|
|
%rename(ccc) ABC<Space::XYZ>::aaa(Space::XYZ t);// will match but with higher precedence than bbb
|
|
%rename(ddd) ABC<Space::XYZ>::aaa(XYZ t); // will not match
|
|
}
|
|
|
|
namespace Space {
|
|
class XYZ {};
|
|
template<typename T> struct ABC {
|
|
void aaa(T t) {}
|
|
};
|
|
}
|
|
%template(ABCXYZ) Space::ABC<Space::XYZ>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Note that <tt>ddd</tt> does not match as there is no namespace resolution for parameter types and the fully qualified type must be specified for template type expansion.
|
|
The following example shows how %rename can be placed within %extend.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
namespace Space {
|
|
%extend ABC {
|
|
%rename(bbb) aaa(T t); // will match but with lower precedence than ccc
|
|
}
|
|
%extend ABC<Space::XYZ> {
|
|
%rename(ccc) aaa(Space::XYZ t);// will match but with higher precedence than bbb
|
|
%rename(ddd) aaa(XYZ t); // will not match
|
|
}
|
|
}
|
|
|
|
namespace Space {
|
|
class XYZ {};
|
|
template<typename T> struct ABC {
|
|
void aaa(T t) {}
|
|
};
|
|
}
|
|
%template(ABCXYZ) Space::ABC<Space::XYZ>;
|
|
</pre>
|
|
</div>
|
|
|
|
|
|
<H2><a name="SWIGPlus_exception_specifications">6.21 Exception specifications</a></H2>
|
|
|
|
|
|
<p>
|
|
When C++ programs utilize exceptions, exceptional behavior is sometimes specified as
|
|
part of a function or method declaration. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Error { };
|
|
|
|
class Foo {
|
|
public:
|
|
...
|
|
void blah() throw(Error);
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If an exception specification is used, SWIG automatically generates
|
|
wrapper code for catching the indicated exception and, when possible,
|
|
rethrowing it into the target language, or converting it into an error
|
|
in the target language otherwise. For example, in Python, you can
|
|
write code like this:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
f = Foo()
|
|
try:
|
|
f.blah()
|
|
except Error, e:
|
|
# e is a wrapped instance of "Error"
|
|
</pre>
|
|
</div>
|
|
|
|
<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#Typemaps_throws_typemap">"throws" typemap</a> section.
|
|
</p>
|
|
|
|
<p>
|
|
Since exception specifications are sometimes only used sparingly, this alone may not be enough to
|
|
properly handle C++ exceptions. To do that, a different set of special SWIG directives are used.
|
|
Consult the "<a href="Customization.html#Customization_exception">Exception handling with %exception</a>" section for details.
|
|
The next section details a way of simulating an exception specification or replacing an existing one.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_catches">6.22 Exception handling with %catches</a></H2>
|
|
|
|
|
|
<p>
|
|
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#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 "...".
|
|
For example,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
struct EBase { virtual ~EBase(); };
|
|
struct Error1 : EBase { };
|
|
struct Error2 : EBase { };
|
|
struct Error3 : EBase { };
|
|
struct Error4 : EBase { };
|
|
|
|
%catches(Error1, Error2, ...) Foo::bar();
|
|
%catches(EBase) Foo::blah();
|
|
|
|
class Foo {
|
|
public:
|
|
...
|
|
void bar();
|
|
void blah() throw(Error1, Error2, Error3, Error4);
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
For the <tt>Foo::bar()</tt> method, which can throw anything,
|
|
SWIG will generate catch handlers for <tt>Error1</tt>, <tt>Error2</tt> as well as a catch all handler (...).
|
|
Each catch handler will convert the caught exception and convert it into a target language error/exception.
|
|
The catch all handler will convert the caught exception into an unknown error/exception.
|
|
</p>
|
|
|
|
<p>
|
|
Without the <tt>%catches</tt> feature being attached to <tt>Foo::blah()</tt>,
|
|
SWIG will generate catch handlers for all of the types in the exception specification, that is, <tt>Error1, Error2, Error3, Error4</tt>.
|
|
However, with the <tt>%catches</tt> feature above,
|
|
just a single catch handler for the base class, <tt>EBase</tt> will be generated to convert the C++ exception into a target language error/exception.
|
|
</p>
|
|
|
|
|
|
<H2><a name="SWIGPlus_nn33">6.23 Pointers to Members</a></H2>
|
|
|
|
|
|
<p>
|
|
Starting with SWIG-1.3.7, there is limited parsing support for pointers to C++ class members.
|
|
For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
double do_op(Object *o, double (Object::*callback)(double, double));
|
|
extern double (Object::*fooptr)(double, double);
|
|
%constant double (Object::*FOO)(double, double) = &Object::foo;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Although these kinds of pointers can be parsed and represented by the
|
|
SWIG type system, few language modules know how to handle them due to
|
|
implementation differences from standard C pointers. Readers are
|
|
<em>strongly</em> advised to consult an advanced text such as the "The
|
|
Annotated C++ Manual" for specific details.
|
|
</p>
|
|
|
|
<p>
|
|
When pointers to members are supported, the pointer value might appear as a special
|
|
string like this:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
>>> print(example.FOO)
|
|
_ff0d54a800000000_m_Object__f_double_double__double
|
|
>>>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this case, the hexadecimal digits represent the entire value of the
|
|
pointer which is usually the contents of a small C++ structure on most
|
|
machines.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG's type-checking mechanism is also more limited when working with
|
|
member pointers. Normally SWIG tries to keep track of inheritance
|
|
when checking types. However, no such support is currently provided
|
|
for member pointers.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_smart_pointers">6.24 Smart pointers and operator->()</a></H2>
|
|
|
|
|
|
<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 class template where
|
|
the <tt>-></tt> operator has been overloaded. This class is then wrapped
|
|
around some other class. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
// Smart-pointer class
|
|
template<class T> class SmartPtr {
|
|
T *pointee;
|
|
public:
|
|
SmartPtr(T *p) : pointee(p) { ... }
|
|
T *operator->() {
|
|
return pointee;
|
|
}
|
|
...
|
|
};
|
|
|
|
// Ordinary class
|
|
class Foo_Impl {
|
|
public:
|
|
int x;
|
|
virtual void bar();
|
|
...
|
|
};
|
|
|
|
// Smart-pointer wrapper
|
|
typedef SmartPtr<Foo_Impl> Foo;
|
|
|
|
// Create smart pointer Foo
|
|
Foo make_Foo() {
|
|
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();
|
|
}
|
|
|
|
// Call the wrapped smart pointer proxy class in the target language 'Foo'
|
|
%template(Foo) SmartPtr<Foo_Impl>;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
A key feature of this approach is that by defining
|
|
<tt>operator-></tt> the methods and attributes of the object
|
|
wrapped by a smart pointer are transparently accessible. For example,
|
|
expressions such as these (from the previous example),
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
f->x
|
|
f->bar()
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
are transparently mapped to the following
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
(f.operator->())->x;
|
|
(f.operator->())->bar();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When generating wrappers, SWIG tries to emulate this functionality to
|
|
the extent that it is possible. To do this, whenever
|
|
<tt>operator->()</tt> is encountered in a class, SWIG looks at its
|
|
returned type and uses it to generate wrappers for accessing
|
|
attributes of the underlying object. For example, wrapping the above
|
|
code produces wrappers like this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
int Foo_x_get(Foo *f) {
|
|
return (*f)->x;
|
|
}
|
|
void Foo_x_set(Foo *f, int value) {
|
|
(*f)->x = value;
|
|
}
|
|
void Foo_bar(Foo *f) {
|
|
(*f)->bar();
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
These wrappers take a smart-pointer instance as an argument, but
|
|
dereference it in a way to gain access to the object returned by
|
|
<tt>operator->()</tt>. You should carefully compare these wrappers
|
|
to those in the first part of this chapter (they are slightly
|
|
different).
|
|
</p>
|
|
|
|
<p>
|
|
The end result is that access looks very similar to C++. For
|
|
example, you could do this in Python:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
>>> f = make_Foo()
|
|
>>> print(f.x)
|
|
0
|
|
>>> f.bar()
|
|
>>>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When generating wrappers through a smart-pointer, SWIG tries to
|
|
generate wrappers for all methods and attributes that might be
|
|
accessible through <tt>operator->()</tt>. This includes any methods
|
|
that might be accessible through inheritance. However, there are a number of restrictions:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Member variables and methods are wrapped through a smart
|
|
pointer. Enumerations, constructors, and destructors are not wrapped.
|
|
</li>
|
|
|
|
<li><p>If the smart-pointer class and the underlying object both define a method or
|
|
variable of the same name, then the smart-pointer version has precedence. For
|
|
example, if you have this code</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
int x;
|
|
};
|
|
|
|
class Bar {
|
|
public:
|
|
int x;
|
|
Foo *operator->();
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
then the wrapper for <tt>Bar::x</tt> accesses the <tt>x</tt> defined in <tt>Bar</tt>, and
|
|
not the <tt>x</tt> defined in <tt>Foo</tt>.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
If your intent is to only expose the smart-pointer class in the interface, it is not necessary to wrap both
|
|
the smart-pointer class and the class for the underlying object. However, you must still tell SWIG about both
|
|
classes if you want the technique described in this section to work. To only generate wrappers for the
|
|
smart-pointer class, you can use the %ignore directive. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%ignore Foo;
|
|
class Foo { // Ignored
|
|
};
|
|
|
|
class Bar {
|
|
public:
|
|
Foo *operator->();
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Alternatively, you can import the definition of <tt>Foo</tt> from a separate file using
|
|
<tt>%import</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Note:</b> When a class defines <tt>operator->()</tt>, the operator itself is wrapped
|
|
as a method <tt>__deref__()</tt>. For example:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
f = Foo() # Smart-pointer
|
|
p = f.__deref__() # Raw pointer from operator->
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Note:</b> To disable the smart-pointer behavior, use <tt>%ignore</tt> to ignore
|
|
<tt>operator->()</tt>. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%ignore Bar::operator->;
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<b>Note:</b> Smart pointer support was first added in SWIG-1.3.14.
|
|
</p>
|
|
|
|
<H2><a name="SWIGPlus_ref_unref">6.25 C++ reference counted objects - ref/unref feature</a></H2>
|
|
|
|
|
|
<p>
|
|
Another similar idiom in C++ is the use of reference counted objects. Consider for example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class RCObj {
|
|
// implement the ref counting mechanism
|
|
int add_ref();
|
|
int del_ref();
|
|
int ref_count();
|
|
|
|
public:
|
|
virtual ~RCObj() = 0;
|
|
|
|
int ref() const {
|
|
return add_ref();
|
|
}
|
|
|
|
int unref() const {
|
|
if (ref_count() == 0 || del_ref() == 0 ) {
|
|
delete this;
|
|
return 0;
|
|
}
|
|
return ref_count();
|
|
}
|
|
};
|
|
|
|
|
|
class A : RCObj {
|
|
public:
|
|
A();
|
|
int foo();
|
|
};
|
|
|
|
|
|
class B {
|
|
A *_a;
|
|
|
|
public:
|
|
B(A *a) : _a(a) {
|
|
a->ref();
|
|
}
|
|
|
|
~B() {
|
|
a->unref();
|
|
}
|
|
};
|
|
|
|
int main() {
|
|
A *a = new A(); // (count: 0)
|
|
a->ref(); // 'a' ref here (count: 1)
|
|
|
|
B *b1 = new B(a); // 'a' ref here (count: 2)
|
|
if (1 + 1 == 2) {
|
|
B *b2 = new B(a); // 'a' ref here (count: 3)
|
|
delete b2; // 'a' unref, but not deleted (count: 2)
|
|
}
|
|
|
|
delete b1; // 'a' unref, but not deleted (count: 1)
|
|
a->unref(); // 'a' unref and deleted (count: 0)
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In the example above, the 'A' class instance 'a' is a reference counted
|
|
object, which can't be deleted arbitrarily since it is shared between
|
|
the objects 'b1' and 'b2'. 'A' is derived from a <i>Reference Counted
|
|
Object</i> 'RCObj', which implements the ref/unref idiom.
|
|
</p>
|
|
|
|
<p>
|
|
To tell SWIG that 'RCObj' and all its derived classes are reference
|
|
counted objects, use the "ref" and "unref" <a href="Customization.html#Customization_features">features</a>.
|
|
These are also available as <tt>%refobject</tt> and <tt>%unrefobject</tt>, respectively.
|
|
For example:
|
|
</p>
|
|
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%module example
|
|
...
|
|
|
|
%feature("ref") RCObj "$this->ref();"
|
|
%feature("unref") RCObj "$this->unref();"
|
|
|
|
%include "rcobj.h"
|
|
%include "A.h"
|
|
...
|
|
</pre>
|
|
</div>
|
|
|
|
<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.
|
|
</p>
|
|
|
|
<p>
|
|
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)
|
|
b1 = B(a) # C++ ref 'a (count: 2)
|
|
if 1 + 1 == 2:
|
|
b2 = B(a) # C++ ref 'a' (count: 3)
|
|
return a # 'b1' and 'b2' are released and deleted, C++ unref 'a' twice (count: 1)
|
|
|
|
a = create_A() # (count: 1)
|
|
exit # 'a' is released, SWIG unref 'a' called in the destructor wrapper (count: 0)
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Note that the user doesn't explicitly need to call 'a->ref()' nor 'a->unref()'
|
|
(and neither 'delete a'). Instead, SWIG takes cares of executing the "ref"
|
|
and "unref" calls as needed. If the user doesn't specify the
|
|
"ref/unref" feature for a type, SWIG will produce code equivalent to defining these
|
|
features:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%feature("ref") ""
|
|
%feature("unref") "delete $this;"
|
|
</pre>
|
|
</div>
|
|
|
|
<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.
|
|
</p>
|
|
|
|
<p>
|
|
The <a href="Customization.html#Customization_ownership">%newobject feature</a> is designed to indicate to
|
|
the target language that it should take ownership of the returned object.
|
|
When used in conjunction with a type that has the "ref" feature associated with it, it additionally emits the
|
|
code in the "ref" feature into the C++ wrapper.
|
|
Consider wrapping the following factory function in addition to the above:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%newobject AFactory;
|
|
A *AFactory() {
|
|
return new A();
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The <tt>AFactory</tt> function now acts much like a call to the <tt>A</tt> constructor with respect to memory handling:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
a = AFactory() # SWIG ref 'a' due to %newobject (count: 1)
|
|
exit # 'a' is released, SWIG unref 'a' called in the destructor wrapper (count: 0)
|
|
</pre>
|
|
</div>
|
|
|
|
|
|
|
|
<H2><a name="SWIGPlus_nn35">6.26 Using declarations and inheritance</a></H2>
|
|
|
|
|
|
<p>
|
|
C++ <tt>using</tt> declarations are sometimes used to introduce members of
|
|
base classes. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {
|
|
public:
|
|
int blah(int x);
|
|
};
|
|
|
|
class Bar {
|
|
public:
|
|
double blah(double x);
|
|
};
|
|
|
|
class FooBar : public Foo, public Bar {
|
|
public:
|
|
using Foo::blah;
|
|
using Bar::blah;
|
|
char *blah(const char *x);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In this example, the <tt>using</tt> declarations make different
|
|
versions of the overloaded <tt>blah()</tt> method accessible from the
|
|
derived class. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
FooBar *f;
|
|
f->blah(3); // Ok. Invokes Foo::blah(int)
|
|
f->blah(3.5); // Ok. Invokes Bar::blah(double)
|
|
f->blah("hello"); // Ok. Invokes FooBar::blah(const char *);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
SWIG emulates the same functionality when creating wrappers. For example, if
|
|
you wrap this code in Python, the module works just like you would expect:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
>>> import example
|
|
>>> f = example.FooBar()
|
|
>>> f.blah(3)
|
|
>>> f.blah(3.5)
|
|
>>> f.blah("hello")
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
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">
|
|
<pre>
|
|
class Foo {
|
|
protected:
|
|
int x;
|
|
int blah(int x);
|
|
};
|
|
|
|
class Bar : public Foo {
|
|
public:
|
|
using Foo::x; // Make x public
|
|
using Foo::blah; // Make blah public
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
This also works in SWIG---the exposed declarations will be wrapped normally.
|
|
</p>
|
|
|
|
<p>
|
|
When <tt>using</tt> declarations are used as shown in these examples, declarations
|
|
from the base classes are copied into the derived class and wrapped normally. When
|
|
copied, the declarations retain any properties that might have been attached using
|
|
<tt>%rename</tt>, <tt>%ignore</tt>, or <tt>%feature</tt>. Thus, if a method is
|
|
ignored in a base class, it will also be ignored by a <tt>using</tt> declaration.
|
|
</p>
|
|
|
|
<p>
|
|
Because a <tt>using</tt> declaration does not provide fine-grained
|
|
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 modify the C++ code to handle SWIG differently such as:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class FooBar : public Foo, public Bar {
|
|
public:
|
|
#ifndef SWIG
|
|
using Foo::blah;
|
|
using Bar::blah;
|
|
#else
|
|
int blah(int x); // explicitly tell SWIG about other declarations
|
|
double blah(double x);
|
|
#endif
|
|
|
|
char *blah(const char *x);
|
|
};
|
|
</pre>
|
|
</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 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>
|
|
class Foo {
|
|
public:
|
|
int blah(int );
|
|
double blah(double);
|
|
};
|
|
|
|
class Bar : public Foo {
|
|
public:
|
|
using Foo::blah; // Only introduces blah(double);
|
|
int blah(int);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<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">
|
|
<pre>
|
|
%rename(blah_long) Foo::blah(long);
|
|
class Foo {
|
|
public:
|
|
int blah(int);
|
|
long blah(long); // Renamed to blah_long
|
|
};
|
|
|
|
class Bar : public Foo {
|
|
public:
|
|
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>
|
|
|
|
|
|
<p>
|
|
If the target language supports the nested classes concept (like Java), the nested C++ classes
|
|
are wrapped as nested target language proxy classes. (In case of Java - "static" nested classes.)
|
|
Only public nested classes are wrapped. Otherwise there is little difference between nested and
|
|
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
|
|
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:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%rename (Bar_Foo) Bar::Foo;
|
|
class Foo {};
|
|
class Bar {
|
|
public:
|
|
class Foo {};
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If a nested class, within an outer class, has to be used as a template parameter within the outer class, then the template will
|
|
have to be instantiated with <tt>%template</tt> before the beginning of the outer class.
|
|
An example can be found in the
|
|
<a href="#SWIGPlus_template_nested_class_example">Templates</a> section.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Compatibility Note:</b>
|
|
Prior to SWIG-3.0.0, there was limited nested class support. Nested classes were treated as opaque pointers.
|
|
However, there was a workaround for nested class support in these older versions requiring the user to replicate
|
|
the nested class in the global scope, adding in a typedef for the nested class in the global scope and
|
|
using the "nestedworkaround" feature on the nested class. This resulted in approximately the
|
|
same behaviour as the "flatnested" feature. With proper nested class support now available in SWIG-3.0.0, this
|
|
feature was deprecated and has now been removed. If you see the following error:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:8: Error: Unknown directive '%nestedworkaround'
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
consider using the "flatnested" feature discussed above which generates a non-nested proxy class, like the
|
|
"nestedworkaround" feature did. Alternatively, use the default nested class code generation, which may generate an
|
|
equivalent to a nested proxy class in the target language, depending on the target language support.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG-1.3.40 and earlier versions did not have the <tt>nestedworkaround</tt> feature
|
|
and the generated code resulting from parsing nested classes did not always compile.
|
|
Nested class warnings could also not be suppressed using %warnfilter.
|
|
</p>
|
|
|
|
|
|
<H2><a name="SWIGPlus_const">6.28 A brief rant about const-correctness</a></H2>
|
|
|
|
|
|
<p>
|
|
A common issue when working with C++ programs is dealing with all
|
|
possible ways in which the <tt>const</tt> qualifier (or lack thereof)
|
|
will break your program, all programs linked against your program, and
|
|
all programs linked against those programs.
|
|
</p>
|
|
|
|
<p>
|
|
Although SWIG knows how to correctly deal with <tt>const</tt> in its
|
|
internal type system and it knows how to generate wrappers that are
|
|
free of const-related warnings, SWIG does not make any attempt to preserve
|
|
const-correctness in the target language. Thus, it is possible to
|
|
pass <tt>const</tt> qualified objects to non-const methods and functions.
|
|
For example, consider the following code in C++:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
const Object * foo();
|
|
void bar(Object *);
|
|
|
|
...
|
|
// C++ code
|
|
void blah() {
|
|
bar(foo()); // Error: bar discards const
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Now, consider the behavior when wrapped into a Python module:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
>>> bar(foo()) # Okay
|
|
>>>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Although this is clearly a violation of the C++ type-system, fixing
|
|
the problem doesn't seem to be worth the added implementation
|
|
complexity that would be required to support it in the SWIG run-time type
|
|
system. There are no plans to change this in future releases
|
|
(although we'll never rule anything out entirely).
|
|
</p>
|
|
|
|
<p>
|
|
The bottom line is that this particular issue does not appear to be a problem
|
|
for most SWIG projects. Of course, you might want to consider
|
|
using another tool if maintaining constness is the most important part
|
|
of your project.
|
|
</p>
|
|
|
|
<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>
|
|
If you're wrapping serious C++ code, you might want to pick up a copy
|
|
of "The Annotated C++ Reference Manual" by Ellis and Stroustrup. This
|
|
is the reference document we use to guide a lot of SWIG's C++ support.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|
|
|
|
<!-- LocalWords: destructors Enums Namespaces const SWIG's STL OO adaptor tcl
|
|
-->
|
|
<!-- LocalWords: debuggable cxx OBJS Wiki accessor nodefault makedefault
|
|
-->
|
|
<!-- LocalWords: notabstract CopyFoo
|
|
-->
|