jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update docs

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@6977 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Marcelo Matus 2005-02-22 19:48:03 +00:00
commit fd2fe8dd36
2 changed files with 134 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

110
SWIG/Doc/Manual/Python.html
View file

@ -239,8 +239,8 @@ using comands like this (shown for Linux):
<blockquote><pre>
$ 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
</pre></blockquote>
@ -1502,6 +1502,8 @@ public:
Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
Complex(const Complex &amp;c) : rpart(c.rpart), ipart(c.ipart) { }
Complex &amp;operator=(const Complex &amp;c);
Complex operator+=(const Complex &amp;c) const;
Complex operator+(const Complex &amp;c) const;
Complex operator-(const Complex &amp;c) const;
Complex operator*(const Complex &amp;c) const;
@ -1524,6 +1526,12 @@ When wrapped, it works like you expect:
10.0
&gt;&gt;&gt; e.im()
12.0
&gt;&gt;&gt; c += d
&gt;&gt;&gt; c.re()
10.0
&gt;&gt;&gt; c.im()
12.0
</pre>
</blockquote>
@ -1541,15 +1549,12 @@ friend Complex operator+(double, const Complex &amp;c);
</pre>
</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,
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:
<blockquote>
<pre>
%rename(Complex_add_dc) operator+(double, const Complex &amp;);
...
Complex operator+(double, const Complex &amp;c);
</pre>
</blockquote>
@ -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.
</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>
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>
<b>Note:</b> The director typemaps for return types based in const
references, such as
<H3><a name="Python_nn39"></a>26.5.7 Miscellaneous</H3>
<blockquote>
<pre>
class Foo {
&hellip;
virtual const int& bar();
&hellip;
};
</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 {
&hellip;
virtual int bar();
&hellip;
};
</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>
<H2><a name="Python_nn40"></a>26.6 Common customization features</H2>
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.
<H3><a name="Python_nn41"></a>26.6.1 C/C++ helper functions</H3>
@ -3220,21 +3263,22 @@ like this:
</pre>
</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:
A detailed list of available methods can be found in the "<a
href="Typemaps.html#Typemaps">Typemaps</a>" chapter.
<blockquote>
<pre>
$ swig -python -co python.swg
'python.swg' checked out from the SWIG library.
$ cat python.swg
</pre>
</blockquote>
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 <tt>typemaps.i</tt> file.
<H3><a name="Python_nn56"></a>26.8.3 Typemap variables</H3>

74
SWIG/Doc/Manual/SWIGPlus.html
View file

@ -767,7 +767,8 @@ Members declared as <tt>const</tt> are wrapped as read-only members and do not c
<H2><a name="SWIGPlus_nn17"></a>6.9 Friends</H2>
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:
<blockquote>
<pre>
@ -780,26 +781,41 @@ public:
</pre>
</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:
then the <tt>friend</tt> declaration does result in a wrapper code
equivalent to one generated for the following declaration
<blockquote>
<pre>
class Foo {
public:
...
friend void blah(Foo *f); // Ignored
...
};
void blah(Foo *f); // Generates wrappers
void blah(Foo *f);
</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.
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>
@ -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.
<p>
<b>Note:</b> The special treatment for references to primitive datatypes is necessary to provide
more seamless integration with more advanced C++ wrapping applications---especially related to
templates and the STL. This was first added in SWIG-1.3.12.
</p>
<H2><a name="SWIGPlus_nn19"></a>6.11 Pass and return by value</H2>
@ -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.
<b>Note:</b> Further optimizations are enabled when using the
<tt>-fvirtual</tt> option, which avoids the regenerating of wrapper
functions for virtual members that are already defined in a base
class.
</p>
<H2><a name="SWIGPlus_nn21"></a>6.13 A brief discussion of multiple inheritance, pointers, and type checking</H2>
@ -2140,7 +2162,7 @@ public:
%extend {
char *__str__() {
static char temp[256];
sprintf(temp,"[ %g, %g, %g ]", v-&gt;x,v-&gt;y,v-&gt;z);
sprintf(temp,"[ %g, %g, %g ]", self-&gt;x,self-&gt;y,self-&gt;z);
return &amp;temp[0];
}
}
@ -2604,6 +2626,23 @@ public:
</pre>
</blockquote>
or simply
<blockquote>
<pre>
class Foo {
public:
template&lt;class T&gt; void bar(T x, T y) { ... };
...
};
...
%template(barint) Foo::bar&lt;int&gt;;
%template(bardouble) Foo::bar&lt;double&gt;;
</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.
@ -2637,7 +2676,8 @@ Miraculously, you will find that each expansion of <tt>Foo</tt> has member
functions <tt>bari()</tt> and <tt>bard()</tt> added.
<p>
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:
</p>
<blockquote>
@ -3422,8 +3462,8 @@ accessible through <tt>operator-&gt;()</tt>. This includes any methods
that might be accessible through inheritance. However, there are a number of restrictions:
<ul>
<li>Only member variables and methods are wrapped through a smart pointer. Static members, enumerations,
constructors, and destructors are not wrapped.
<li>Member variables and methods are wrapped through a smart
pointer. Enumerations, constructors, and destructors are not wrapped.
</li>
<li>If the smart-pointer class and the underlying object both define a method or