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.
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 vector 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.
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 special C++ adaptor or proxy classes, it does not rely upon templates, nor does it use 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.
Most 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 most target languages also provide a high-level OO interface via proxy classes. A few general details about proxies can be found at the end of this chapter. However, more detailed coverage can be found in the documentation for each target language.
The following C++ features are not currently supported :
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).
When wrapping C++ code, it is critical that SWIG be called with the `-c++' 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 -c++ flag, SWIG will either issue a warning or a large number of syntax errors if it encounters C++ code in an interface file.
When compiling and linking the resulting wrapper file, it is normal to use the C++ compiler. For example:
Unfortunately, the process varies slightly on each machine. Make sure you refer to the documentation on each target language for further details. The SWIG Wiki also has further details.$ swig -c++ -tcl example.i $ c++ -c example_wrap.cxx $ c++ example_wrap.o $(OBJS) -o example.so
To generate wrappers for this class, SWIG first reduces the class to a collection of low-level C-style accessor functions. The next few sections describe this process. Later parts of the chapter decribe a higher level interface based on proxy classes.%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); };
List * new_List(void) { return new List; } void delete_List(List *l) { delete l; }
%nodefault can also take a class name. For example:%nodefault; // Disable creation of constructor/destructor class Foo { ... }; %makedefault;
Compatibility Note: The generation of default constructors/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 %nodefault or the -nodefault command line option. Furthermore, in order for SWIG to properly generate (or not generate) default constructors, it must be able to gather information from both the private and protected 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 %nodefault to fix the problem.%nodefault Foo; // Disable for class Foo only.
First, SWIG won't generate wrappers for protected or private constructors. For example:
class Foo { protected: Foo(); // Not wrapped. public: ... };
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:
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:class Bar { public: Bar(); // Not wrappped. Bar is abstract. virtual void spam(void) = 0; }; class Grok : public Bar { public: Grok(); // Not wrapped. No implementation of abstract spam(). };
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:% swig -Wall -python module.i
More information about %feature can be found in the Customization features chapter.%feature("notabstract") Foo; class Foo : public Bar { public: Foo(); // Generated no matter what---not abstract. ... };
then the copy constructor can be used as follows:class List { public: List(); List(const List &); // Copy constructor ... };
If the target language does not support overloading, then the copy constructor is available through a special function like this:x = new_List() # Create a list y = new_List(x) # Copy list x
List *copy_List(List *f) { return new List(*f); }
Note: For a class X, SWIG only treats a constructor as a copy constructor if it can be applied to an object of type X or X *. 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 X(const X &), X(X &), and X(X *) are handled as copy constructors in SWIG.
Note: SWIG does not generate a copy constructor wrapper unless one is explicitly declared in the class. This differs from the treatment of default constructors and destructors.
Compatibility note: 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:
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 new_CopyFoo(). This is the same as in older versions.class Foo { public: Foo(); %name(CopyFoo) Foo(const Foo &); ... };
This translation is the same even if the member function has been declared as virtual.int List_search(List *obj, char *value) { return obj->search(value); }
It should be noted that SWIG does not actually create a C accessor function in the code it generates. Instead, member access such as obj->search(value) is directly inlined into the generated wrapper functions. However, the name and calling convention of the wrappers match the accessor function prototype described above.
Usually, static members are accessed as functions with names in which the class name has been prepended with an underscore. For example, List_print.
However, the implementation restricts the use of default arguments to values that are public. The following example illustrates a very subtle semantic incompatibility between SWIG and C++:class Foo { public: void bar(int x, int y = 3); };
When this occurs, you will get a couple of warning messages like this:class Foo { private: int spam; public: void bar(int x, int y = spam); // Illegal in SWIG. Private default value };
This incompatibility arises 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). The full set of arguments are needed in the wrappers in order to support a number of advanced customization features and the use of default arguments in ANSI C (which is not part of the ANSI standard).example.i:15. Warning 'spam' is private in this context. example.i:15. Warning. Can't set default argument (ignored)
There are several somewhat clumsy ways to work around this problem (which are not discussed here). However, a simpler solution may be to reconsider your design--is it really that critical to make the default argument private?
A read-only member can be created using the %immutable and %mutable directives. 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.int List_length_get(List *obj) { return obj->length; } int List_length_set(List *obj, int value) { obj->length = value; return value; }
Alternatively, you can specify an immutable member in advance like this:class List { public: ... %immutable; int length; %mutable; ... };
Similarly, all data attributes declared as const are wrapped as read-only members.%immutable List::length; ... class List { ... int length; // Immutable by above directive ... };
There are some subtle issues when wrapping data members that are themselves classes. For instance, if you had another class like this,
then access to the items member actually uses pointers. For example:class Foo { public: List items; ...
More information about this can be found in the "Structure data members" section of the SWIG Basics chapter.List *Foo_items_get(Foo *self) { return &self->items; } void Foo_items_set(Foo *self, List *value) { self->items = *value; }
Compatibility note: Read-only access used to be controlled by a pair of directives %readonly and %readwrite. Although these directives still work, they generate a warning message. Simply change the directives to %immutable; and %mutable; to silence the warning. Don't forget the extra semicolon!
Compatibility note: 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
and nothing was known about size_t, then accessors would be written to work with size_t *. Starting in SWIG-1.3.12, this behavior has been modified. Specifically, pointers will only be used if SWIG knows that a datatype corresponds to a structure or class. Therefore, the above code would be wrapped into accessors involving size_t. This change is subtle, but it smooths over a few problems related to structure wrapping and some of SWIG's customization features.struct Foo { size_t len; };
By default, members of a class definition are assumed to be private until you explicitly give a `public:' declaration (This is the same convention used by C++).
A subtle access problem relates to default values of member functions. Specifically, default values must be public. Please go back to the section on default arguments for further details.
Generates the following set of constants in the target scripting language :class Swig { public: enum {ALE, LAGER, PORTER, STOUT}; };
Members declared as const are wrapped as read-only members and do not create constants.Swig_ALE = Swig::ALE Swig_LAGER = Swig::LAGER Swig_PORTER = Swig::PORTER Swig_STOUT = Swig::STOUT
then the friend declaration does not result in any wrapper code. On the other hand, a declaration of the function itself will work fine. For instance:class Foo { public: ... friend void blah(Foo *f); ... };
Unlike normal member functions or static member functions, a friend declaration does not define a method that operates on an instance of an object nor does it define a declaration in the scope of the class. Therefore, it would make no sense for SWIG to create wrappers as such.class Foo { public: ... friend void blah(Foo *f); // Ignored ... }; void blah(Foo *f); // Generates wrappers
class Foo { public: double bar(double &a); }
is accessed using a function similar to this:
As a special case, most language modules pass const references to primitive datatypes (int, short, float, etc.) by value instead of pointers. For example, if you have a function like this,double Foo_bar(Foo *obj, double *a) { obj->bar(*a); }
it is called from a script as follows:void foo(const int &x);
Functions that return a reference are remapped to return a pointer instead. For example:foo(3) # Notice pass by value
Generates code like this:class Bar { public: Foo &spam(); };
However, functions that return const references to primitive datatypes (int, short, etc.) normally return the result as a value rather than a pointer. For example, a function like this,Foo *Bar_spam(Bar *obj) { Foo &result = obj->spam(); return &result; }
will return integers such as 37 or 42 in the target scripting language rather than a pointer to an integer.const int &bar();
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.
Note: 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.
If no information is supplied about Vector, SWIG creates a wrapper function similar to the following:Vector cross_product(Vector a, Vector b);
In order for the wrapper code to compile, Vector must define a copy constructor and a default constructor.Vector *wrap_cross_product(Vector *a, Vector *b) { Vector x = *a; Vector y = *b; Vector r = cross_product(x,y); return new Vector(r); }
If Vector is defined as class in the interface, but it does not support a default constructor, SWIG changes the wrapper code by encapsulating the arguments inside a special C++ template wrapper class. This produces a wrapper that looks like this:
This transformation is a little sneaky, but it provides support for pass-by-value even when a class does not provide a default constructor and it makes it possible to properly support a number of SWIG's customization options. The definition of SwigValueWrapper can be found by reading the SWIG wrapper code. This class is really nothing more than a thin wrapper around a pointer.Vector cross_product(Vector *a, Vector *b) { SwigValueWrapper<Vector> x = *a; SwigValueWrapper<Vector> y = *b; SwigValueWrapper<Vector> r = cross_product(x,y); return new Vector(r); }
Note: 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.
Note: This template transformation is new in SWIG-1.3.11 and may be refined in future SWIG releases. In practice, it is only necessary to do this for classes that don't define a default constructor.
Note: The use of this template only occurs when objects are passed or returned by value. It is not used for C++ pointers or references.
Note: The performance of pass-by-value is especially bad for large objects and should be avoided if possible (consider using references instead).
SWIG does not support private or protected inheritance (it is parsed, but it has no effect on the generated code). Note: private and protected inheritance do not define an "isa" relationship between classes so it would have no effect on type-checking anyways.
The following example shows how SWIG handles inheritance. For clarity, the full C++ code has been omitted.
// 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(); }
When wrapped into Python, we can now perform the following operations :
In this example, Circle and Square objects have been created. Member functions can be invoked on each object by making calls to Circle_area, Square_area, and so on. However, the same results can be accomplished by simply using the Shape_area function on either object.$ 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 >>>
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 set_location() is only accessible as Shape_set_location() and not as Circle_set_location() or Square_set_location(). Of course, the Shape_set_location() function will accept any kind of object derived from Shape. Similarly, accessor functions for the attributes x and y are generated as Shape_x_get(), Shape_x_set(), Shape_y_get(), and Shape_y_set(). Functions such as Circle_x_get() are not available--instead you should use Shape_x_get().
Although the low-level C-like interface is functional, most language modules also produce a higher level OO interface using proxy classes. This approach is described later and can be used to provide a more natural C++ interface.
Note: For the best results, SWIG requires all base classes to be defined in an interface. Otherwise, you may get an warning message like this:
If any base class is undefined, SWIG still generates correct type relationships. For instance, a function accepting a Foo * will accept any object derived from Foo regardless of whether or not SWIG actually wrapped the Foo 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 %import directive to include the file that defines Foo. %import simply gathers type information, but doesn't generate wrappers. Alternatively, you could just define Foo as an empty class in the SWIG interface.example:18. Nothing known about class 'Foo'. Ignored.
Note: typedef-names can be used as base classes. For example:
Similarly, typedef allows unnamed structures to be used as base classes. For example:class Foo { ... }; typedef Foo FooObj; class Bar : public FooObj { // Ok. Base class is Foo ... };
typedef struct { ... } Foo; class Bar : public Foo { // Ok. ... };
Compatibility Note: 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 Circle_x_get(), Square_x_get(), Circle_set_location(), and Square_set_location(). 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. Future versions of SWIG may apply further optimizations such as not regenerating wrapper functions for virtual members that are already defined in a base class.
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?_808fea88_p_Circle
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 void *. This means that any C++ type information associated with the pointer is lost in the conversion.
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:
Now, consider the following code that uses void *.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; }
In this code, both A_function() and B_function() may legally accept an object of type C * (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 p points to an object of type C, the casting operation doesn't work like you would expect. Internally, this has to do with the data representation of C. With multiple inheritance, the data from each base class is stacked together. For example:C *c = new C(); void *p = (void *) c; ... int x = A_function((A *) p); int y = B_function((B *) p);
Because of this stacking, a pointer of type C * may change value when it is converted to a A * or B *. However, this adjustment does not occur if you are converting from a void *.------------ <--- (C *), (A *) | A | |------------| <--- (B *) | B | ------------
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).
One might be inclined to fix this problem using some variation of dynamic_cast<>. The only problem is that it doesn't work with void pointers, it requires RTTI support, and it only works with polymorphic classes (i.e., classes that define one or more virtual functions).
The bottom line: learn to live with type-tagged pointers.
This will create the functions List_find, List_delete, and a function named new_ListSize for the overloaded constructor.class List { public: List(); %name(ListSize) List(int maxsize); ~List(); int search(char *value); %name(find) void insert(char *); %name(delete) void remove(char *); char *get(int n); int length; static void print(List *l); };
The %name directive can be applied to all members including constructors, destructors, static functions, data members, and enumeration values.
The class name prefix can also be changed by specifying
Although the %name() directive can be used to help deal with overloaded methods, it really doesn't work very well because it requires a lot of additional markup in your interface. Keep reading for a better solution.%name(newname) class List { ... }
The function is used in a completely natural way. For example:void foo(int x) { printf("x is %d\n", x); } void foo(char *x) { printf("x is '%s'\n", x); }
Overloading works in a similar manner for methods and constructors. For example if you have this code,>>> foo(3) x is 3 >>> foo("hello") x is 'hello' >>>
it might be used like thisclass Foo { public: Foo(); Foo(const Foo &); // Copy constructor void bar(int x); void bar(char *s, int y); };
>>> f = Foo() # Create a Foo >>> f.bar(3) >>> g = Foo(f) # Copy Foo >>> f.bar("hello",2)
the order in which the arguments are checked plays a rather critical role.void foo(char *x); void foo(int x);
To implement overloading, 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:
Using these precedence values, overloaded methods with the same number of required arguments are sorted in increased order of precedence values.Type Precedence ---------------- ---------- TYPE * 0 (High) void * 20 Integers 40 Floating point 60 char 80 Strings 100 (Low)
This may sound very confusing, but an example will help. Consider the following collection of overloaded methods:
The first rule simply ranks the functions by required argument count. This would produce the following list: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);
The second rule, simply refines the ranking by looking at argument type precedence values.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);
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.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);
If you're still confused, don't worry about it---SWIG is probably doing the right thing.
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 (int and long may even be the same precision). Therefore, when SWIG encounters this situation, it may generate a warning message like this:void foo(int x); void foo(long x);
This means that the second overloaded function will be inaccessible from the scripting interface---SWIG does not know how to disambiguate it from an earlier method.example.i:4: Warning(509): Overloaded foo(long) is shadowed by foo(int) at example.i:3.
Ambiguity problems are known to arise in the following situations:
When wrapping an overloaded function, there is a chance that you will get an error message like this:
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 swig-dev@cs.uchicago.edu.example.i:3: Warning(467): Overloaded foo(int) not supported (no type checking rule for 'int').
If you get an error message such as the following,
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.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 )
The other alternative is to rename one of the methods. This can be done using %rename. For example:%ignore foo(long); void foo(int); void foo(long); // Ignored. Oh well.
The %ignore and %rename 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:%rename(foo_long) foo(long); void foo(int); void foo(long); // Accessed as foo_long()
If you only want the renaming to apply to a certain scope, the C++ scope resolution operator (::) can be used. For example:/* 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' ... };
When a renaming operator is applied to a class as in Spam::foo(int), 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:%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
It is also possible to include %rename specifications in the class definition itself. For example:%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 ... };
In this case, the %rename directives still get applied across the entire inheritance hierarchy, but it's no longer necessary to explicitly specify the class prefix Spam::.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 ... };
A special form of %rename can be used to apply a renaming just to class members (of all classes):
Note: the *:: 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 swig-dev@cs.uchicago.edu).%rename(foo_i) *::foo(int); // Only rename foo(int) if it appears in a class.
Although this discussion has primarily focused on %rename all of the same rules also apply to %ignore. For example:
When applied to a base class, %ignore forces all definitions in derived clases to disappear. For example, %ignore Spam::foo(double) will eliminate foo(double) in Spam and all classes derived from Spam.%ignore foo(double); // Ignore all foo(double) %ignore Spam::foo; // Ignore foo in class Spam %ignore Spam::foo(double); // Ignore foo(double) in class Spam %ignore *::foo(double); // Ignore foo(double) in all classes
Notes on %rename and %ignore:
%module foo /* Rename these overloaded functions */ %rename(foo_i) foo(int); %rename(foo_d) foo(double); %include "header.h"
%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
and this%rename(bar) foo; %rename(foo_i) Spam::foo(int); %rename(Foo) Spam::foo;
(the declarations are not stored in a linked list and order has no importance). Of course, a repeated %rename directive will change the setting for a previous %rename directive if exactly the same name, scope, and parameters are supplied.%rename(Foo) Spam::foo; %rename(bar) foo; %rename(foo_i) Spam::foo(int);
the declaration %rename(name) Foo::bar() only applies to the unqualified member bar(). However, an often overlooked C++ feature is that classes can define two different overloaded members that differ only in their qualifiers, like this:class Foo { public: ... void bar(); ... };
In this case, the renaming operator would only apply to the first method. If you wanted to rename the qualified member function, use %rename(name) Foo::bar() const instead. Similarly, if you merely wanted to ignore one of the declarations, use %ignore with the full qualification. For example, the following directive would tell SWIG to ignore the const version of bar() above:class Foo { public: ... void bar(); // Unqualified member void bar() const; // Qualified member (OK) ... };
%ignore Foo::bar() const; // Ignore bar() const, but leave other bar() alone
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.
When operator declarations appear, they are handled in exactly the same manner as regular methods. However, the names of these methods are set to strings like "operator +" or "operator -". 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 "operator +" in Python--there won't be any way to call it.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; } };
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 %rename directive. For example, in Python a declaration similar to this is used:
This binds the + operator to a method called __add__ (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:%rename(__add__) Complex::operator+;
When used in the target language, it may now be possible to use the overloaded operator normally. For example:_wrap_Complex___add__(args) { ... get args ... obj->operator+(args); ... }
It is important to realize that there is nothing magical happening here. The %rename directive really only picks a valid method name. If you wrote this:>>> a = Complex(3,4) >>> b = Complex(5,2) >>> c = a + b # Invokes __add__ method
The resulting scripting interface might work like this:%rename(add) operator+;
All of the techniques described to deal with overloaded functions also apply to operators. For example:a = Complex(3,4) b = Complex(5,2) c = a.add(b) # Call a.operator+(b)
The last part of this example illustrates how multiple definitions of the operator- method might be handled.%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 -
Handling operators in this manner is mostly straightforward. However, there are a few subtle issues to keep in mind:
SWIG simply ignores all friend declarations. Furthermore, it doesn't know how to associate the associated operator+ with the class (because it's not a member of the class).class Complex { public: friend Complex operator+(Complex &, double); }; Complex operator+(Complex &, double);
It's still possible to make a wrapper for this operator, but you'll have to handle it like a normal function. For example:
%rename(add_complex_double) operator+(Complex &, double);
%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 ]", v->x,v->y,v->z); return &temp[0]; } } };
This code adds a __str__ 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 print command.
The %extend directive follows all of the same conventions as its use with C structures. Please refer to the SWIG Basics chapter for further details.>>> >>> v = Vector(); >>> v.x = 3 >>> v.y = 4 >>> v.z = 0 >>> print(v) [ 3.0, 4.0, 0.0 ] >>>
Compatibility note: The %extend directive is a new name for the %addmethods directive. Since %addmethods could be used to extend a structure with more than just methods, a more suitable directive name has been chosen.
There are some restrictions on the use of non-type arguments. Specifically, they have to be simple literals and not expressions. For example:void foo(vector<int> *a, int n); void bar(list<int,100> *x);
The type system is smart enough to figure out clever games you might try to play with typedef. For instance, consider this code:void bar(list<int,100> *x); // OK void bar(list<int,2*50> *x); // Illegal
In this case, vector<Integer> is exactly the same type as vector<int>. The wrapper for foo() will accept either variant.typedef int Integer; void foo(vector<int> *x, vector<Integer> *y);
Starting with SWIG-1.3.7, simple C++ template declarations can also be wrapped. SWIG-1.3.12 greatly expands upon the earlier implementation. Before discussing this any further, there are a few things you need to know about template wrapping. First, a bare C++ template 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., vector<int>, array<double>, etc.). Second, an instantiation name such as vector<int> 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 intvector when creating a wrapper.
To illustrate, consider the following template definition:
By itself, this template declaration is useless--SWIG simply ignores it because it doesn't know how to generate any code until unless a definition of T is provided.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]; } };
One way to create wrappers for a specific template instantiation is to simply provide an expanded version of the class directly like this:
The %rename directive is needed to give the template class an appropriate identifier name in the target language (most languages would not recognize C++ template syntax as a valid class name). The rest of the code is the same as what would appear in a normal class definition.%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); };
Since manual expansion of templates gets old in a hurry, the %template directive can be used to create instantiations of a template class. Semantically, %template is simply a shortcut---it expands template code in exactly the same way as shown above. Here are some examples:
The argument to %template() 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:/* Instantiate a few different versions of the template */ %template(intList) List<int>; %template(doubleList) List<double>;
SWIG can also generate wrappers for function templates using a similar technique. For example:%template(intList) List<int>; ... typedef List<int> intList; // OK
In this case, maxint and maxdouble become unique names for specific instantiations of the function.// 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>;
The number of arguments supplied to %template should match that in the original template definition. Template default arguments are supported. For example:
template vector<typename T, int max=100> class vector { ... }; %template(intvec) vector<int>; // OK %template(vec1000) vector<int,1000>; // OK
The %template directive should not be used to wrap the same template instantiation more than once in the same scope. This will generate an error. For example:
%template(intList) List<int>; %template(Listint) List<int>; // Error. Template already wrapped.
This error is caused because the template expansion results in two identical classes with the same name. This generates a symbol table conflict. Besides, it probably more efficient to only wrap a specific instantiation only once in order to reduce the potential for code bloat.
Since the type system knows how to handle typedef, it is generally not necessary to instantiate different versions of a template for typenames that are equivalent. For instance, consider this code:
In this case, vector<Integer> is exactly the same type as vector<int>. Any use of Vector<Integer> is mapped back to the instantiation of vector<int> created earlier. Therefore, it is not necessary to instantiate a new class for the type Integer (doing so is redundant and will simply result in code bloat).%template(intList) vector<int>; typedef int Integer; ... void foo(vector<Integer> *x);
When a template is instantiated using %template, information about that class is saved by SWIG and used elsewhere in the program. For example, if you wrote code like this,
then SWIG knows that List<int> was already wrapped as a class called intList and arranges to handle the inheritance correctly. If, on the other hand, nothing is known about List<int>, you will get a warning message similar to this:... %template(intList) List<int>; ... class UltraList : public List<int> { ... };
example.h:42. Nothing known about class 'List<int >' (ignored). example.h:42. Maybe you forgot to instantiate 'List<int >' using %template.
If a template class inherits from another template class, you need to make sure that base classes are instantiated before derived classes. For example:
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 an warning message.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>;
Occassionally, you may need to tell SWIG about base classes that are defined by templates, but which aren't supposed to be wrapped. Since SWIG is not able to automatically instantiate templates for this purpose, you must do it manually. To do this, simply use %template with no name. For example:
// Instantiate traits<double,double>, but don't wrap it. %template() traits<double,double>;
If you have to instantiate a lot of different classes for many different types, you might consider writing a SWIG macro. For example:
%define TEMPLATE_WRAP(T,prefix) %template(prefix ## Foo) Foo<T>; %template(prefix ## Bar) Bar<T>; ... %enddef TEMPLATE_WRAP(int, int) TEMPLATE_WRAP(double, double) TEMPLATE_WRAP(char *, String) ...
The SWIG template mechanism does support specialization. For instance, if you define a class like this,
then SWIG will use this code whenever the user expands List<int>. 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 %typemap, %extend, and so forth can be attached to a specialization to provide customization for specific types.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); };
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.
SWIG should be able to handle most simple uses of partial specialization. However, it may fail to match templates properly in more complicated cases. For example, if you have this code,template<class T> class List<T*> { private: T *data; int nitems; int maxitems; public: List(int max); ~List(); void append(int obj); int length(); T get(int n); };
SWIG isn't able to match it properly for instantiations like Foo<int *, int *>. This problem is not due to parsing, but due to the fact that SWIG does not currently implement all of the C++ argument deduction rules.template<class T1, class T2> class Foo<T1, T2 *> { };
Member function templates are supported. The underlying principle is the same as for normal templates--SWIG can't create a wrapper unless you provide more information about types. For example, a class with a member template might look like this:
To expand the template, simply use %template inside the class.class Foo { public: template<class T> void bar(T x, T y) { ... }; ... };
Or, if you want to leave the original class definition alone, just do this:class Foo { public: template<class T> void bar(T x, T y) { ... }; ... %template(barint) bar<int>; %template(bardouble) bar<double>; };
Note: because of the way that templates are handled, the %template directive must always appear after the definition of the template to be expanded.class Foo { public: template<class T> void bar(T x, T y) { ... }; ... }; ... %extend Foo { %template(barint) bar<int>; %template(bardouble) bar<double>; };
When used with members, the %template directive may be placed in another template class. Here is a slightly perverse example:
Miraculously, you will find that each expansion of Foo has member functions bari() and bard() added.// 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>;
A common use of member templates is to define constructors for copies and conversions. For example:
This declaration is perfectly acceptable to SWIG, but the constructor template will be ignored unless you explicitly expand it. To do that, you could expand a few versions of the constructor in the template class itself. For example: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) { } };
When using %extend in this manner, notice how you can still use the template parameters in the original template definition.%extend pair { %template(pair) pair<T1,T2>; // Generate default copy constructor };
Alternatively, you could expand the constructor template in selected instantiations. For example:
Admittedly, this isn't very pretty or automatic. However, it's probably better than nothing--well, maybe.// Instantiate a few versions %template(pairii) pair<int,int>; %template(pairdd) pair<double,double>; // Create a conversion constructor from int to double %extend pair<double,double> { %template(pairdd_from_pairii) pair<int,int>; // Conversion constructor };
If all of this isn't quite enough and you really want to make someone's head explode, SWIG directives such as %rename, %extend, and %typemap can be included directly in template definitions. For example:
In this example, the extra SWIG directives are propagated to every template instantiation.// 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 */ ... } } };
It is also possible to separate these declarations from the template class. For example:
%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() { }; ... };
When %extend 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 %extend directive can be used to add additional methods to a specific instantiation. For example:
%template(intList) List<int>; %extend List<int> { void blah() { printf("Hey, I'm an List<int>!\n"); } };
Needless to say, SWIG's template support provides plenty of opportunities to break the universe. That said, an important final point is that SWIG does not perform extensive error checking of templates! 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 will hopefully check this when it compiles the resulting wrapper file, there is no practical reason for SWIG to duplicate this functionality (besides, none of the SWIG developers are masochistic enough to want to implement this right now).
Finally, there are a few limitations in SWIG's current support for templates:
This will generate a name conflict error message in SWIG. To silence the error message, use %ignore:template<class T> void foo(T x) { }; template<class T> void foo(T x, T y) { }; // Error. foo already defined.
In this case, %template will only work with the first definition. To create a wrapper for the second definition, just do it manually:%ignore foo(T,T);
%name(foo2int) void foo<int>(int x, int y);
Compatibility Note: 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.
Compatibility Note: In earlier versions of SWIG, the %template directive introduced a new class name. This name could then be used with other directives. For example:
This behavior is no longer supported. Instead, you should use the original template name as the class name. For example:%template(vectori) vector<int>; %extend vectori { void somemethod() { } };
Similar changes apply to typemaps and other customization features.%template(vectori) vector<int>; %extend vector<int> { void somemethod() { } };
Members of the namespace are accessed in C++ by prepending the namespace prefix to names. For example:namespace math { double sin(double); double cos(double); class Complex { double im,re; public: ... }; ... };
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 using.double x = math::sin(1.0); double magitude(math::Complex *c); math::Complex c; ...
Similarly, the contents of an entire namespace can be made available like this:using math::Complex; double magnitude(Complex *c); // Namespace prefix stripped
Alternatively, a namespace can be aliased:using namespace math; double x = sin(1.0); double magnitude(Complex *c);
Using combinations of these features, it is possible to write head-exploding code like this:namespace M = math; double x = M::sin(1.0); double magnitude(M::Complex *c);
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 class names!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);
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,
then SWIG simply creates three wrapper functions bar(), spam(), and blah() 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.%module foo namespace foo { void bar(int); void spam(); } namespace bar { void blah(); }
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.
Because namespaces are flattened, it is possible for symbols defined in different namespaces to generate a name conflict in the target language. For example:
When this conflict occurs, you will get an error message that resembles this:namespace A { void foo(int); } namespace B { void foo(double); }
To resolve this error, simply use %rename to disambiguate the declarations. For example:example.i:26. Error. 'foo' is multiply defined in the generated module. example.i:23. Previous declaration of 'foo'
Similarly, %ignore can be used to ignore declarations.%rename(B_foo) B::foo; ... namespace A { void foo(int); } namespace B { void foo(double); // Gets renamed to B_foo }
using declarations do not have any effect on the generated wrapper code. They are ignored by SWIG language modules and they do not result in any code. However, these declarations are used by the internal type system to track type-names. Therefore, if you have code like this:
SWIG knows that Integer is the same as A::Integer which is the same as int.namespace A { typedef int Integer; } using namespace A; void foo(Integer x);
Namespaces may be combined with templates. If necessary, the %template directive can be used to expand a template defined in a different namespace. For example:
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 global 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 using 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:namespace foo { template<typename 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. }
In this case, SWIG correctly resolves the added method parameters and return type to foo::Integer. However, since function bodies aren't parsed and such code is emitted in the global namespace, this code produces a compiler error about Integer. To fix the problem, make sure you use fully qualified names. For example: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; } };
%extend foo::bar { Integer add(Integer x, Integer y) { foo::Integer r = x + y; // Ok. return r; } };
Note: SWIG does not propagate using declarations to the resulting wrapper code. If these declarations appear in an interface, they should also appear in any header files that might have been included in a %{ ... %} section. In other words, don't insert extra using declarations into a SWIG interface unless they also appear in the underlying C++ code.
Note: Code inclusion directives such as %{ ... %} or %inline %{ ... %} 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:
// 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 */ ... %} }
Note: When the %extend directive is used inside a namespace, the namespace name is included in the generated functions. For example, if you have code like this,
the added method blah() is mapped to a function int foo_bar_blah(foo::bar *self, int x). This function resides in the global namespace.namespace foo { class bar { public: %extend { int blah(int x); }; }; }
Note: 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.
Note: Namespaces have a subtle effect on the wrapping of conversion operators. For instance, suppose you had an interface like this:
To wrap the conversion function, you might be inclined to write this:namespace foo { class bar; class spam { public; ... operator bar(); // Conversion of spam -> bar ... }; }
The only problem is that it doesn't work. The reason it doesn't work is that bar is not defined in the global scope. Therefore, to make it work, do this instead:%rename(tofoo) foo::spam::operator bar();
%rename(tofoo) foo::spam::operator foo::bar();
Note: The flattening of namespaces is only intended to serve as a basic namespace implementation. Since namespaces are a new addition to SWIG, none of the target language modules are currently programmed with any namespace awareness. In the future, language modules may or may not provide more advanced namespace support.
If an exception specification is used, SWIG automatically generates wrapper code for catching the indicated exception and converting it into an error in the target language. In certain language modules, wrapped exception classes themselves can be used to catch errors. For example, in Python, you can write code like this:class Error { }; class Foo { public: ... void blah() throw(Error); ... };
Obviously, the exact details of how exceptions are handled depend on the target language module.f = Foo() try: f.blah() except Error,e: # e is a wrapped instance of "Error"
Since exception specifiers 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 "Customization features" chapter for details.
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 strongly advised to consult an advanced text such as the "The Annotated C++ Manual" for specific details.double do_op(Object *o, double (Object::*callback)(double,double)); extern double (Object::*fooptr)(double,double); %constant double (Object::*FOO)(double,double) = &Object::foo;
When pointers to members are supported, the pointer value might appear as a special string like this:
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.>>> print example.FOO _ff0d54a800000000_m_Object__f_double_double__double >>>
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.
A key feature of this approach is that by defining operator-> 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),// Smart-pointer class template<class T> class SmartPtr { T *pointee; public: ... 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(new Foo_Impl()); } // Do something with smart pointer Foo void do_something(Foo f) { printf("x = %d\n", f->x); f->bar(); }
are transparently mapped to the followingf->x f->bar()
When generating wrappers, SWIG tries to emulate this functionality to the extent that it is possible. To do this, whenever operator->() 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:(f.operator->())->x; (f.operator->())->bar();
These wrappers take a smart-pointer instance as an argument, but dereference it in a way to gain access to the object returned by operator->(). You should carefully compare these wrappers to those in the first part of this chapter (they are slightly different).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(); }
The end result is that access looks very similar to C++. For example, you could do this in Python:
When generating wrappers through a smart-pointer, SWIG tries to generate wrappers for all methods and attributes that might be accessible through operator->(). This includes any methods that might be accessible through inheritance. However, there are a number of restrictions:>>> f = make_Foo() >>> print f.x 0 >>> f.bar() >>>
then the wrapper for Bar::x accesses the x defined in Bar, and not the x defined in Foo.class Foo { public: int x; }; class Bar { public: int x; Foo *operator->(); };
Alternatively, you can import the definition of Foo from a separate file using %import.%ignore Foo; class Foo { // Ignored }; class Bar { public: Foo *operator->(); ... };
Note: When a class defines operator->(), the operator itself is wrapped as a method __deref__(). For example:
f = Foo() # Smart-pointer p = f.__deref__() # Raw pointer from operator->
Note: To disable the smart-pointer behavior, use %ignore to ignore operator->(). For example:
%ignore Bar::operator->;
Note: Smart pointer support was first added in SWIG-1.3.14.
In this example, the using declarations make different versions of the overloaded blah() method accessible from the derived class. For example: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); };
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: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 *);
using declarations can also be used to change access when applicable. For example:>>> import example >>> f = example.FooBar() >>> f.blah(3) >>> f.blah(3.5) >>> f.blah("hello")
This also works in SWIG---the exposed declarations will be wrapped normally.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 };
When using 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 %rename, %ignore, or %feature. Thus, if a method is ignored in a base class, it will also be ignored by a using declaration.
Because a using declaration does not provide fine-grained control over the declarations that get imported, it may be difficult to manage such declarations in applications that make heavy use of SWIG customization features. If you can't get using to work correctly, you can always change the interface to the following:
Notes: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); };
class Foo { public: int blah(int ); double blah(double); }; class Bar : public Foo { public: using Foo::blah; // Only imports blah(double); int blah(int); };
%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 imports blah(int) double blah(double x); };
class Foo { public: #ifndef SWIG class Bar { public: ... }; #endif Foo(); ~Foo(); ... };
Also, as a rule of thumb, SWIG should not be used on raw C++ source files.
Although SWIG knows how to correctly deal with const 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 const qualified objects to non-const methods and functions. For example, consider the following code in C++:
Now, consider the behavior when wrapped into a Python module:const Object * foo(); void bar(Object *); ... // C++ code void blah() { bar(foo()); // Error: bar discards const };
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).>>> bar(foo()) # Okay >>>
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.
Using C++ as pseudocode, a proxy class looks something like this:class Foo { public: Foo(); ~Foo(); int bar(int x); int x; };
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: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); } };
Again, it's important to emphasize that the low-level accessor functions are always used to construct the proxy classes.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) ...
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.
Now, consider some script code that uses these classes:class Foo { public: Foo(); ~Foo(); int bar(int x); int x; }; class Spam { public: Foo *value; ... };
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 f and s are created in this way. However, the statement s.value is rather curious---when executed, a pointer to f is stored inside another object. This means that the scripting proxy class AND another C++ class share a reference to the same object. To make matters even more interesting, consider the statement g = s.value. When executed, this creates a new proxy class g that provides a wrapper around the C++ object stored in s.value. 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 g results in a second proxy class for f. In other words, a reference to f is now shared by two proxy classes and a C++ class.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
Finally, consider what happens when objects are destroyed. In the statement, g=4, the variable g is reassigned. In many languages, this makes the old value of g available for garbage collection. Therefore, this causes one of the proxy classes to be destroyed. Later on, the statement del f 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 it the object still valid?
To deal with memory management problems, proxy classes always provide an API for controlling ownership. In C++ pseudocode, ownership control might look roughly like this:
Looking at this code, there are a few central features: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(); } ... };