From: Marcelo M. <mar...@us...> - 2005-02-22 19:48:38
|
Update of /cvsroot/swig/SWIG/Doc/Manual In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30957 Modified Files: Python.html SWIGPlus.html Log Message: update docs Index: Python.html =================================================================== RCS file: /cvsroot/swig/SWIG/Doc/Manual/Python.html,v retrieving revision 1.20 retrieving revision 1.21 diff -C2 -d -r1.20 -r1.21 *** Python.html 25 Oct 2004 20:42:08 -0000 1.20 --- Python.html 22 Feb 2005 19:47:37 -0000 1.21 *************** *** 240,245 **** <blockquote><pre> $ swig -python example.i ! $ gcc -c example.c ! $ gcc -c example_wrap.c -I/usr/local/include/python2.0 $ gcc -shared example.o example_wrap.o -o _example.so </pre></blockquote> --- 240,245 ---- <blockquote><pre> $ swig -python example.i ! $ 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 </pre></blockquote> *************** *** 1503,1506 **** --- 1503,1508 ---- 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; *************** *** 1525,1528 **** --- 1527,1536 ---- >>> e.im() 12.0 + >>> c += d + >>> c.re() + 10.0 + >>> c.im() + 12.0 + </pre> </blockquote> *************** *** 1542,1547 **** </blockquote> ! 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, but you may have to encapsulate it in a special function. For example: --- 1550,1554 ---- </blockquote> ! 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: *************** *** 1549,1554 **** <pre> %rename(Complex_add_dc) operator+(double, const Complex &); - ... - Complex operator+(double, const Complex &c); </pre> </blockquote> --- 1556,1559 ---- *************** *** 2377,2392 **** 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. </p> <p> ! 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. </p> ! <H3><a name="Python_nn39"></a>26.5.7 Miscellaneous</H3> --- 2382,2434 ---- 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. </p> + + <H3><a name="Python_nn39"></a>26.5.7 Miscellaneous</H3> + <p> ! 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. </p> ! <p> ! <b>Note:</b> The director typemaps for return types based in const ! references, such as ! ! <blockquote> ! <pre> ! class Foo { ! … ! virtual const int& bar(); ! … ! }; ! </pre> ! </blockquote> ! ! 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. ! ! <blockquote> ! <pre> ! class Foo { ! … ! virtual int bar(); ! … ! }; ! </pre> ! </blockquote> ! ! 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. ! ! </p> *************** *** 2394,2403 **** ! 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. <H3><a name="Python_nn41"></a>26.6.1 C/C++ helper functions</H3> --- 2436,2446 ---- ! 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. <H3><a name="Python_nn41"></a>26.6.1 C/C++ helper functions</H3> *************** *** 3221,3239 **** </blockquote> ! A detailed list of available methods can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" 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 <tt>python.swg</tt> file in the SWIG library. Just issue ! these commands: ! <blockquote> ! <pre> ! $ swig -python -co python.swg ! 'python.swg' checked out from the SWIG library. ! $ cat python.swg ! </pre> ! </blockquote> - Additional typemap examples can also be found in the <tt>typemaps.i</tt> file. <H3><a name="Python_nn56"></a>26.8.3 Typemap variables</H3> --- 3264,3283 ---- </blockquote> ! A detailed list of available methods can be found in the "<a ! href="Typemaps.html#Typemaps">Typemaps</a>" 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 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. <H3><a name="Python_nn56"></a>26.8.3 Typemap variables</H3> Index: SWIGPlus.html =================================================================== RCS file: /cvsroot/swig/SWIG/Doc/Manual/SWIGPlus.html,v retrieving revision 1.16 retrieving revision 1.17 diff -C2 -d -r1.16 -r1.17 *** SWIGPlus.html 11 Nov 2004 21:39:25 -0000 1.16 --- SWIGPlus.html 22 Feb 2005 19:48:03 -0000 1.17 *************** *** 768,772 **** ! Friend declarations are ignored by SWIG. For example, if you have this code: <blockquote> --- 768,773 ---- ! Friend declarations are not longer ignored by SWIG. For example, if ! you have this code: <blockquote> *************** *** 781,786 **** </blockquote> ! then the <tt>friend</tt> declaration does not result in any wrapper code. On the other hand, ! a declaration of the function itself will work fine. For instance: <blockquote> --- 782,787 ---- </blockquote> ! then the <tt>friend</tt> declaration does result in a wrapper code ! equivalent to one generated for the following declaration <blockquote> *************** *** 789,804 **** public: ... - friend void blah(Foo *f); // Ignored - ... }; ! void blah(Foo *f); // Generates wrappers </pre> </blockquote> ! 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. <H2><a name="SWIGPlus_nn18"></a>6.10 References and pointers</H2> --- 790,820 ---- public: ... }; ! void blah(Foo *f); </pre> </blockquote> ! A friend declaration, as in C++, is understood to be in the same scope ! where the class is declared, hence, you can do ! ! <blockquote> ! <pre> ! ! %ignore bar::blah(Foo *f); ! ! namespace bar { ! ! class Foo { ! public: ! ... ! friend void blah(Foo *f); ! ... ! }; ! } ! </pre> ! </blockquote> ! ! and a wrapper for the method 'blah' will not be generated. <H2><a name="SWIGPlus_nn18"></a>6.10 References and pointers</H2> *************** *** 880,883 **** --- 896,901 ---- cause your program to crash. + + <p> <b>Note:</b> The special treatment for references to primitive datatypes is necessary to provide *************** *** 886,889 **** --- 904,908 ---- </p> + <H2><a name="SWIGPlus_nn19"></a>6.11 Pass and return by value</H2> *************** *** 1135,1141 **** 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. </p> --- 1154,1163 ---- 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> *************** *** 2141,2145 **** char *__str__() { static char temp[256]; ! sprintf(temp,"[ %g, %g, %g ]", v->x,v->y,v->z); return &temp[0]; } --- 2163,2167 ---- char *__str__() { static char temp[256]; ! sprintf(temp,"[ %g, %g, %g ]", self->x,self->y,self->z); return &temp[0]; } *************** *** 2605,2608 **** --- 2627,2647 ---- </blockquote> + or simply + + <blockquote> + <pre> + class Foo { + public: + template<class T> void bar(T x, T y) { ... }; + ... + }; + ... + + %template(barint) Foo::bar<int>; + %template(bardouble) Foo::bar<double>; + </pre> + </blockquote> + + Note: because of the way that templates are handled, the <tt>%template</tt> directive must always appear <em>after</em> the definition of the template to be expanded. *************** *** 2638,2642 **** <p> ! A common use of member templates is to define constructors for copies and conversions. For example: </p> --- 2677,2682 ---- <p> ! A common use of member templates is to define constructors for copies ! and conversions. For example: </p> *************** *** 3423,3428 **** <ul> ! <li>Only member variables and methods are wrapped through a smart pointer. Static members, enumerations, ! constructors, and destructors are not wrapped. </li> --- 3463,3468 ---- <ul> ! <li>Member variables and methods are wrapped through a smart ! pointer. Enumerations, constructors, and destructors are not wrapped. </li> |