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

*** empty log message ***

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@3617 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley 2002-08-21 20:09:08 +00:00
commit fb409dbd9d
3 changed files with 208 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

6
swigweb/compare.ht
View file

@ -3,12 +3,6 @@ SWIG Features
<p>
<h2>SWIG Features</h2>
<center>
<em>
"Don't believe everything you read."
</em>
</center>
<p>
In the last five years, dozens of extension building tools have been
released---most of which can be found from the SWIG <a

3
swigweb/index.ht
View file

@ -19,7 +19,8 @@ noncommercial use.
<ul>
<li> <a href="download.html">Download</a> the latest version.
<li> <a href="doc.html">Documentation, papers, and presentations</a>
<li> <a href="compare.html">Compare</a> SWIG with the competition.
<li> <a href="compare.html">Features</a>.
<li> <a href="myths.html">Myths</a> about SWIG.
<li> <a href="mail.html">Mailing List</a>
<li> <a href="bugs.html">Bug tracking</a>
<li> <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SwigWiki!</a>

206
swigweb/myths.ht Normal file
View file

@ -0,0 +1,206 @@
SWIG Myths
<p>
<h2>SWIG Myths</h2>
<center>
<em>
"Don't believe everything you read."
</em>
</center>
<font color="#ff0000"><h4>Myth: SWIG only really works with ANSI C</h4></font>
<h4>Fact:</h4>
SWIG <em>does</em> provide wrapping support for all of ANSI C. However, SWIG has
also included C++ support since it's initial release in 1996. To be fair, early
SWIG releases had limitations, but C++ support has continually improved with
each SWIG release.
<p>
C++ support in current SWIG releases is quite advanced--providing support for nearly
every C++ feature including templates, namespaces, operators, overloaded methods,
and more. The only major C++ feature not supported is nested classes---and we're
working on that. See the <a href="compare.html">Features</a> page for more information.
<font color="#ff0000"><h4>Myth: SWIG wraps C++ into this unusable
low-level C-tran interface.</h4></font>
<h4>Fact:</h4>
When wrapping C++, SWIG does generate a set of low-level procedural
wrappers. However, these are only used as building blocks for
creating a more advanced high-level interface (in fact, users rarely
interact with this layer directly). In nearly all target languages,
SWIG also wraps C++ classes into a nice object-oriented interface that
mirrors the underlying C++ code. In Python, C++ classes
are wrapped as Python classes, in Perl, C++ classes are wrapped as
Perl classes, and so forth. The existence of procedural wrappers is
only an artifact of SWIG's layered approach to wrapper code generation.
<font color="#ff0000"><h4>Myth: SWIG doesn't support overloaded methods/functions</h4></font>
<h4>Fact:</h4>
SWIG provides full support for C++ overloaded methods and functions.
For example, if you have declarations like this:
<blockquote>
<pre>
class Foo {
public:
Foo();
Foo(const Foo &);
void spam(int x);
void spam(double x);
void spam(char *x, int n);
};
</pre>
</blockquote>
They can be used in a completely natural way from most SWIG language modules. For example,
in Python:
<blockquote>
<pre>
>>> f = Foo()
>>> f.spam(3)
>>> f.spam(3.5)
>>> f.spam("hello",5)
>>> g = Foo(f) # Make a copy
</pre>
</blockquote>
Or in Tcl:
<blockquote>
<pre>
% Foo f
% f spam 3
% f spam 3.5
% f spam "hello" 5
% Foo g f
</pre>
</blockquote>
The SWIG implementation of overloading utilizes type categories and a
type precedence scheme that results in the generation of dynamic
dispatch functions. The order in which declarations appear does not matter nor
does SWIG rely on unreliable mechanisms like trial execution (i.e., trying methods
one by one until one happens to execute successfully). Overloading support in SWIG
is much more advanced than that.
<P>
Due to the dynamic nature of scripting languages, it is not possible to
fully disambiguate overloaded methods to the same degree as in C++.
For example, you might have declarations like this:
<blockquote>
<pre>
int foo(int);
long foo(long);
</pre>
</blockquote>
In this case, SWIG provides a number of directives to either rename or ignore
one of the declarations. For example:
<blockquote>
<pre>
%ignore foo(long);
</pre>
</blockquote>
or
<blockquote>
<pre>
%rename(foo_long) foo(long);
</pre>
</blockquote>
<font color="#ff0000"><h4>Myth: SWIG doesn't support basic idiomatic C++ constructs like templates and smart pointers</h4></font>
<h4>Fact:</h4>
SWIG fully supports templates. However, to wrap a template class, you have to
tell SWIG about a particular instantiation. This is easy, just make sure SWIG
knows about the template definition and include a special directive like this:
<blockquote>
<pre>
%template(deque_int) std::deque&lt;int&gt;;
</pre>
</blockquote>
In this case, "deque_int" becomes the target language name for the wrapped object.
You would use it just like a normal class in the extension module:
<blockquote>
<pre>
>>> d = deque_int(100)
>>> d.size()
100
>>>
</pre>
</blockquote>
On the subject of smart-pointers, those are supported too. For example, suppose
you had some code like this:
<blockquote>
<pre>
class Foo {
public:
int x;
int spam(int x);
};
template&lt;class T&gt; class SmartPtr {
public:
...
T *operator-&gt;();
...
};
typedef SmartPtr&lt;Foo&gt; FooPtr;
FooPtr make_Foo();
</pre>
</blockquote>
To wrap this with SWIG, just tell it about a template instantiation. For example:
<blockquote>
<pre>
%template(FooPtr) SmartPtr&lt;Foo&gt;;
</pre>
</blockquote>
Now, in the target language, the wrapper object works just like you would expect:
<blockquote>
<pre>
>>> f = make_Foo()
>>> f.x = 3
>>> f.spam(42)
</pre>
</blockquote>
<font color="#ff0000"><h4>Myth: SWIG is too confusing to use</h4></font>
<h4>Fact:</h4>
SWIG does provide a large number of customization features and options
that can be used to control almost all parts of the wrapper generation
process. These are needed to support power users and to provide the
flexibility needed to solve difficult real-world wrapping problems.
However, none of these features are needed to get started. In fact, most
users find SWIG to be relatively easy to use.