From fd2fe8dd36e8e7f2977b0893abc6e04f7ef13f7f Mon Sep 17 00:00:00 2001 From: Marcelo Matus Date: Tue, 22 Feb 2005 19:48:03 +0000 Subject: [PATCH] update docs git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@6977 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- SWIG/Doc/Manual/Python.html | 110 ++++++++++++++++++++++++---------- SWIG/Doc/Manual/SWIGPlus.html | 74 +++++++++++++++++------ 2 files changed, 134 insertions(+), 50 deletions(-) diff --git a/SWIG/Doc/Manual/Python.html b/SWIG/Doc/Manual/Python.html index 9a5d17692..ceac01993 100644 --- a/SWIG/Doc/Manual/Python.html +++ b/SWIG/Doc/Manual/Python.html @@ -239,8 +239,8 @@ using comands like this (shown for Linux): 
 $ swig -python example.i
-$ gcc -c example.c
-$ gcc -c example_wrap.c -I/usr/local/include/python2.0
+$ gcc -c -fPIC example.c
+$ gcc -c -fPIC example_wrap.c -I/usr/local/include/python2.0
 $ gcc -shared example.o example_wrap.o -o _example.so
@@ -1502,6 +1502,8 @@ 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); + + Complex operator+=(const Complex &c) const; Complex operator+(const Complex &c) const; Complex operator-(const Complex &c) const; Complex operator*(const Complex &c) const; @@ -1524,6 +1526,12 @@ When wrapped, it works like you expect: 10.0 >>> e.im() 12.0 +>>> c += d +>>> c.re() +10.0 +>>> c.im() +12.0 + @@ -1541,15 +1549,12 @@ friend Complex operator+(double, const Complex &c); -then SWIG doesn't know what to do with the friend function--in fact, -it simply ignores it and issues a warning. You can still wrap the operator, +then SWIG ignores it and issues a warning. You can still wrap the operator, but you may have to encapsulate it in a special function. For example: 
 %rename(Complex_add_dc) operator+(double, const Complex &);
-...
-Complex operator+(double, const Complex &c);
@@ -2376,29 +2381,67 @@ Python. Typemaps for input and output of most of the basic types from director classes have been written. These are roughly the reverse of the usual input and output typemaps used by the wrapper code. The typemap -operation names are 'directorin', 'directorout', and 'directorargout'. The director code does -not use any of the other kinds of typemaps yet. It is not clear at this -point which kinds are appropriate and need to be supported. +operation names are 'directorin', 'directorout', and 'directorargout'. +The director code does not use any of the other kinds of typemaps +yet. It is not clear at this point which kinds are appropriate and +need to be supported. +

+ + +

26.5.7 Miscellaneous

+ +

+Director typemaps for STL classes are in place, and hence you should +be able to use std::vector, std::string, etc., as any other raw type.

-Typemaps for STL classes are under construction. So far there is support -for std::string, std::vector, and std::complex, although there's no -guarantee these are fully functional yet. -

+Note: The director typemaps for return types based in const +references, such as -

26.5.7 Miscellaneous

+
+
+class Foo {
+…
+    virtual const int& bar();
+…
+};
+
+
+ +will work only for simple call scenarios. Usually the resulting code +is neither thread or reentrant safe. Hence, the user is adviced to +avoid returning const reference in director methods. For example, +the user could modify the method interface to use a lvalue return +types, when possible, i.e. + +
+
+class Foo {
+…
+    virtual int bar();
+…
+};
+
+
+ +If that is not possible, the user should avoid to enable the +director feature for reentrant, recursive or threaded member +methods that return const references. + +

26.6 Common customization features

-The last section presented the absolute basics of C/C++ wrapping. If you do nothing -but feed SWIG a header file, you will get an interface that mimics the behavior -described. However, sometimes this isn't enough to produce a nice module. Certain -types of functionality might be missing or the interface to certain functions might -be awkward. This section describes some common SWIG features that are used -to improve your the interface to an extension module. +The last section presented the absolute basics of C/C++ wrapping. If +you do nothing but feed SWIG a header file, you will get an interface +that mimics the behavior described. However, sometimes this isn't +enough to produce a nice module. Certain types of functionality might +be missing or the interface to certain functions might be awkward. +This section describes some common SWIG features that are used to +improve your the interface to an extension module.

26.6.1 C/C++ helper functions

@@ -3220,21 +3263,22 @@ like this: -A detailed list of available methods can be found in the "Typemaps" chapter. -However, the best source of typemap information (and examples) is probably the Python module -itself. In fact, all of SWIG's default type handling is defined by typemaps. You can view -these typemaps by looking at the python.swg file in the SWIG library. Just issue -these commands: +A detailed list of available methods can be found in the "Typemaps" chapter. -
-
-$ swig -python -co python.swg
-'python.swg' checked out from the SWIG library.
-$ cat python.swg
-
-
+However, the best source of typemap information (and examples) is +probably the Python module itself. In fact, all of SWIG's default +type handling is defined by typemaps. You can view these typemaps by +looking at the files in the SWIG library. Just take into account that +in the latest versions of swig (1.3.22+), the library files are not +very pristine clear for the casual reader, as they used to be. The +extensive use of macros and other ugly techniques in the latest +version produce a very powerful and consistent python typemap library, +but at the cost of simplicity and pedagogic value. + +To learn how to write a simple or your first typemap, you better take +a look at the SWIG library version 1.3.20 or so. -Additional typemap examples can also be found in the typemaps.i file.

26.8.3 Typemap variables

diff --git a/SWIG/Doc/Manual/SWIGPlus.html b/SWIG/Doc/Manual/SWIGPlus.html index c70e940c9..9afded939 100644 --- a/SWIG/Doc/Manual/SWIGPlus.html +++ b/SWIG/Doc/Manual/SWIGPlus.html @@ -767,7 +767,8 @@ Members declared as const are wrapped as read-only members and do not c

6.9 Friends

-Friend declarations are ignored by SWIG. For example, if you have this code: +Friend declarations are not longer ignored by SWIG. For example, if +you have this code: 
@@ -780,26 +781,41 @@ public:
-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: +then the friend declaration does result in a wrapper code +equivalent to one generated for the following declaration 
 class Foo {
 public:
     ...
-    friend void blah(Foo *f);       // Ignored
-    ...
 };
 
-void blah(Foo *f);       // Generates wrappers
+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. +A friend declaration, as in C++, is understood to be in the same scope +where the class is declared, hence, you can do + +
+
+
+%ignore bar::blah(Foo *f);
+
+namespace bar {
+
+  class Foo {
+  public:
+     ...
+     friend void blah(Foo *f);
+     ...
+  };
+}
+
+
+ +and a wrapper for the method 'blah' will not be generated.

6.10 References and pointers

@@ -879,12 +895,15 @@ 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.

+

6.11 Pass and return by value

@@ -1134,9 +1153,12 @@ 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. +when advanced features like proxy classes are used. + +Note: Further optimizations are enabled when using the +-fvirtual option, which avoids the regenerating of wrapper +functions for virtual members that are already defined in a base +class.

6.13 A brief discussion of multiple inheritance, pointers, and type checking

@@ -2140,7 +2162,7 @@ public: %extend { char *__str__() { static char temp[256]; - sprintf(temp,"[ %g, %g, %g ]", v->x,v->y,v->z); + sprintf(temp,"[ %g, %g, %g ]", self->x,self->y,self->z); return &temp[0]; } } @@ -2604,6 +2626,23 @@ public: +or simply + +
+
+class Foo {
+public:
+     template<class T> void bar(T x, T y) { ... };
+     ...
+};
+...
+
+%template(barint)    Foo::bar<int>;
+%template(bardouble) Foo::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. @@ -2637,7 +2676,8 @@ Miraculously, you will find that each expansion of Foo has member functions bari() and bard() added.

-A common use of member templates is to define constructors for copies and conversions. For example: +A common use of member templates is to define constructors for copies +and conversions. For example:

@@ -3422,8 +3462,8 @@ accessible through operator->(). This includes any methods that might be accessible through inheritance. However, there are a number of restrictions: