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

Merge branch 'master' into doxygen

Browse source 
Fix the usual conflicts in autodoc unit test due to fixing the
divergences in autodoc generation between builtin and default cases in
this branch.
This commit is contained in:
Vadim Zeitlin 2017-09-19 13:54:41 +02:00
commit db65ae5aea
371 changed files with 9815 additions and 3191 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/Manual/Allegrocl.html
View file

@ -155,7 +155,7 @@ SWIG directives. SWIG can be furnished with a header file, but an
interface can also be generated without library headers by supplying a
simple text file--called the interface file, which is typically named
with a <tt>.i</tt> extension--containing any foreign declarations of
identifiers you wish to use. The most common approach is to use a an
identifiers you wish to use. The most common approach is to use an
interface file with directives to parse the needed headers. A straight
parse of library headers will result in usable code, but SWIG
directives provides much freedom in how a user might tailor the

2
Doc/Manual/Android.html
View file

@ -409,7 +409,7 @@ All the steps required to compile and use a simple hierarchy of classes for shap
<p>
First create an Android project called <tt>SwigClass</tt> in a subdirectory called <tt>class</tt>.
The steps below create and build a the JNI C++ app.
The steps below create and build the JNI C++ app.
Adjust the <tt>--target</tt> id as mentioned earlier in the <a href="Android.html#Android_examples_intro">Examples introduction</a>.
</p>

2
Doc/Manual/CCache.html
View file

@ -411,7 +411,7 @@ following conditions need to be met:
<p>
ccache was inspired by the compilercache shell script script written
ccache was inspired by the compilercache shell script written
by Erik Thiele and I would like to thank him for an excellent piece of
work. See
<a href="http://www.erikyyy.de/compilercache/">http://www.erikyyy.de/compilercache/</a>

106
Doc/Manual/CPlusPlus11.html
View file

@ -42,6 +42,7 @@
<li><a href="#CPlusPlus11_noexcept">Exception specifications and noexcept</a>
<li><a href="#CPlusPlus11_alignment">Control and query object alignment</a>
<li><a href="#CPlusPlus11_attributes">Attributes</a>
<li><a href="#CPlusPlus11_ref_qualifiers">Methods with ref-qualifiers</a>
</ul>
<li><a href="#CPlusPlus11_standard_library_changes">Standard library changes</a>
<ul>
@ -877,7 +878,8 @@ so in this case it is entirely possible to pass an int instead of a double to <t
<p>
SWIG correctly parses the new <tt>static_assert</tt> declarations.
SWIG correctly parses the new <tt>static_assert</tt> declarations (though 3.0.12 and earlier
had a bug which meant this wasn't accepted at file scope).
This is a C++ compile time directive so there isn't anything useful that SWIG can do with it.
</p>
@ -970,6 +972,104 @@ int [[attr1]] i [[attr2, attr3]];
[[noreturn, nothrow]] void f [[noreturn]] ();
</pre></div>
<H3><a name="CPlusPlus11_ref_qualifiers">7.2.29 Methods with ref-qualifiers</a></H3>
<p>
C++11 non-static member functions can be declared with ref-qualifiers.
Member functions declared with a <tt>&amp;</tt> lvalue ref-qualifiers are wrapped like any other function without ref-qualifiers.
Member functions declared with a <tt>&amp;&amp;</tt> rvalue ref-qualifiers are ignored by default
as they are unlikely to be required from non-C++ languages where the concept of <i>rvalue-ness</i>
for the implied *this pointer does not apply.
The warning is hidden by default, but can be displayed as described in the section on <a href="Warnings.html#Warnings_nn4">Enabling extra warnings</a>.
</p>
<p>
Consider:
</p>
<div class="code"><pre>
struct RQ {
void m1(int x) &amp;;
void m2(int x) &amp;&amp;;
};
</pre></div>
<p>
The only wrapped method will be the lvalue ref-qualified method <tt>m1</tt>
and if SWIG is run with the <tt>-Wextra</tt> command-line option, the following warning will be issued indicating <tt>m2</tt> is not wrapped:
</p>
<div class="shell">
<pre>
example.i:7: Warning 405: Method with rvalue ref-qualifier m2(int) &amp;&amp; ignored.
</pre>
</div>
<p>
If you unignore the method as follows, wrappers for <tt>m2</tt> will be generated:
</p>
<div class="code"><pre>
%feature("ignore", "0") RQ::m2(int x) &amp;&amp;;
struct RQ {
void m1(int x) &amp;;
void m2(int x) &amp;&amp;;
};
</pre></div>
<p>
Inspection of the generated C++ code, will show that <tt>std::move</tt> is used on the instance
of the <tt>RQ *</tt> class:
</p>
<div class="code"><pre>
RQ *arg1 = (RQ *) 0 ;
int arg2 ;
arg1 = ...marshalled from target language...
arg2 = ...marshalled from target language...
std::move(*arg1).m2(arg2);
</pre></div>
<p>
This will compile but when run, the move effects may not be what you want.
As stated earlier, rvalue ref-qualifiers aren't really applicable outside the world of C++.
However, if you really know what you are doing, full control over the call to the method is
possible via the low-level "action" feature.
This feature completely replaces the call to the underlying function, that is, the last line in the snippet of code above.
</p>
<div class="code"><pre>
%feature("ignore", "0") RQ::m2(int x) &amp;&amp;;
%feature("action") RQ::m2(int x) &amp;&amp; %{
RQ().m2(arg2);
%}
struct RQ {
void m1(int x) &amp;;
void m2(int x) &amp;&amp;;
};
</pre></div>
<p>
resulting in:
</p>
<div class="code"><pre>
RQ *arg1 = (RQ *) 0 ;
int arg2 ;
arg1 = ...marshalled from target language...
arg2 = ...marshalled from target language...
RQ().m2(arg2);
</pre></div>
<p>
<b>Compatibility note:</b> SWIG-4.0.0 was the first version to support ref-qualifiers.
</p>
<H2><a name="CPlusPlus11_standard_library_changes">7.3 Standard library changes</a></H2>
@ -994,7 +1094,8 @@ Variadic template support requires further work to provide substantial tuple wra
<p>
The new hash tables in the STL are <tt>unordered_set</tt>, <tt>unordered_multiset</tt>, <tt>unordered_map</tt>, <tt>unordered_multimap</tt>.
These are not available in SWIG, but in principle should be easily implemented by adapting the current STL containers.
These are not available in all target languages.
Any missing support can in principle be easily implemented by adapting the current STL containers.
</p>
<H3><a name="CPlusPlus11_regular_expressions">7.3.4 Regular expressions</a></H3>
@ -1175,5 +1276,6 @@ Phew, that is a lot of hard work to get a callback working.
You could just go with the more attractive option of just using <tt>double</tt> as the return type in the function declaration instead of <tt>result_of</tt>!
</p>
</body>
</html>

44
Doc/Manual/CSharp.html
View file

@ -677,7 +677,7 @@ As a result, we get the following method in the module class:
<div class="code">
<pre>
public static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) {
examplePINVOKE.myArrayCopy(sourceArray, targetArray, nitems);
examplePINVOKE.myArrayCopy(sourceArray, targetArray, nitems);
}
</pre>
</div>
@ -997,9 +997,9 @@ When the following C# code is executed:
<div class="code">
<pre>
public class runme {
static void Main() {
example.positivesonly(-1);
}
static void Main() {
example.positivesonly(-1);
}
}
</pre>
</div>
@ -1772,7 +1772,7 @@ should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C
<p>
When using <a href="Modules.html#Modules">multiple modules</a> it is is possible to compile each SWIG generated wrapper
When using <a href="Modules.html#Modules">multiple modules</a> it is possible to compile each SWIG generated wrapper
into a different assembly.
However, by default the generated code may not compile if
generated classes in one assembly use generated classes in another assembly.
@ -1846,12 +1846,12 @@ and the following usage from C# after running the code through SWIG:
<div class="code">
<pre>
Wheel wheel = new Bike(10).getWheel();
Console.WriteLine("wheel size: " + wheel.size);
// Simulate a garbage collection
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
global::System.Console.WriteLine("wheel size: " + wheel.size);
Wheel wheel = new Bike(10).getWheel();
Console.WriteLine("wheel size: " + wheel.size);
// Simulate a garbage collection
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
global::System.Console.WriteLine("wheel size: " + wheel.size);
</pre>
</div>
@ -1980,9 +1980,9 @@ and more or less equivalent usage from C#
<div class="code">
<pre>
Container container = new Container();
Element element = new Element(20);
container.setElement(element);
Container container = new Container();
Element element = new Element(20);
container.setElement(element);
</pre>
</div>
@ -1993,14 +1993,14 @@ In order to understand why, consider a garbage collection occuring...
<div class="code">
<pre>
Container container = new Container();
Element element = new Element(20);
container.setElement(element);
Console.WriteLine("element.value: " + container.getElement().value);
// Simulate a garbage collection
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
global::System.Console.WriteLine("element.value: " + container.getElement().value);
Container container = new Container();
Element element = new Element(20);
container.setElement(element);
Console.WriteLine("element.value: " + container.getElement().value);
// Simulate a garbage collection
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
global::System.Console.WriteLine("element.value: " + container.getElement().value);
</pre>
</div>

38
Doc/Manual/Contents.html
View file

@ -228,7 +228,6 @@
<li><a href="SWIGPlus.html#SWIGPlus_nn12">Static members</a>
<li><a href="SWIGPlus.html#SWIGPlus_member_data">Member data</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn15">Protection</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn16">Enums and constants</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn17">Friends</a>
@ -236,16 +235,27 @@
<li><a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn20">Inheritance</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a>
<li><a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a>
<li><a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a>
<li><a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in overloading</a>
<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn28">Wrapping overloaded operators</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn28">Overloaded operators</a>
<li><a href="SWIGPlus.html#SWIGPlus_class_extension">Class extension</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_template_directive">The %template directive</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_functions">Function templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_classes">Default template arguments</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_class_inheritance">Template base classes</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_specialization">Template specialization</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_member">Member templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_scoping">Scoping and templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_template_more">More on templates</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_namespaces">Namespaces</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nspace">The nspace feature for namespaces</a>
@ -300,6 +310,7 @@
<li><a href="CPlusPlus11.html#CPlusPlus11_noexcept">Exception specifications and noexcept</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_alignment">Control and query object alignment</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_attributes">Attributes</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_ref_qualifiers">Methods with ref-qualifiers</a>
</ul>
<li><a href="CPlusPlus11.html#CPlusPlus11_standard_library_changes">Standard library changes</a>
<ul>
@ -347,26 +358,32 @@
<div class="sectiontoc">
<ul>
<li><a href="Library.html#Library_nn2">The %include directive and library search path</a>
<li><a href="Library.html#Library_nn3">C Arrays and Pointers</a>
<li><a href="Library.html#Library_nn3">C arrays and pointers</a>
<ul>
<li><a href="Library.html#Library_nn4">cpointer.i</a>
<li><a href="Library.html#Library_carrays">carrays.i</a>
<li><a href="Library.html#Library_nn6">cmalloc.i</a>
<li><a href="Library.html#Library_nn7">cdata.i</a>
</ul>
<li><a href="Library.html#Library_nn8">C String Handling</a>
<li><a href="Library.html#Library_nn8">C string handling</a>
<ul>
<li><a href="Library.html#Library_nn9">Default string handling</a>
<li><a href="Library.html#Library_nn10">Passing binary data</a>
<li><a href="Library.html#Library_nn11">Using %newobject to release memory</a>
<li><a href="Library.html#Library_nn12">cstring.i</a>
</ul>
<li><a href="Library.html#Library_stl_cpp_library">STL/C++ Library</a>
<li><a href="Library.html#Library_stl_cpp_library">STL/C++ library</a>
<ul>
<li><a href="Library.html#Library_std_string">std::string</a>
<li><a href="Library.html#Library_std_vector">std::vector</a>
<li><a href="Library.html#Library_stl_exceptions">STL exceptions</a>
<li><a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a>
<ul>
<li><a href="Library.html#Library_shared_ptr_basics">shared_ptr basics</a>
<li><a href="Library.html#Library_shared_ptr_inheritance">shared_ptr and inheritance</a>
<li><a href="Library.html#Library_shared_ptr_templates">shared_ptr and templates</a>
<li><a href="Library.html#Library_shared_ptr_directors">shared_ptr and directors</a>
</ul>
<li><a href="Library.html#Library_std_auto_ptr">auto_ptr smart pointer</a>
</ul>
<li><a href="Library.html#Library_nn16">Utility Libraries</a>
@ -1614,6 +1631,11 @@
<li><a href="Python.html#Python_nn77">Byte string output conversion</a>
<li><a href="Python.html#Python_2_unicode">Python 2 Unicode</a>
</ul>
<li><a href="Python.html#Python_multithreaded">Support for Multithreaded Applications</a>
<ul>
<li><a href="Python.html#Python_thread_UI">UI for Enabling Multithreading Support</a>
<li><a href="Python.html#Python_thread_performance">Multithread Performance</a>
</ul>
</ul>
</div>
<!-- INDEX -->

6
Doc/Manual/Customization.html
View file

@ -356,7 +356,7 @@ In this case, the exception handler is only attached to declarations
named "allocate". This would include both global and member
functions. The names supplied to <tt>%exception</tt> follow the same
rules as for <tt>%rename</tt> described in the section on
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>.
For example, if you wanted to define
an exception handler for a specific class, you might write this:
</p>
@ -516,7 +516,7 @@ The special variables are often used in situations where method calls are logged
$action
}
catch (MemoryError) {
croak("Out of memory in $decl");
croak("Out of memory in $decl");
}
}
void log(const char *message);
@ -796,7 +796,7 @@ involving <tt>%feature</tt>:
</div>
<p>
The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
section applies to all <tt>%feature</tt> directives.
In fact the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>.
The matching rules mean that features are very flexible and can be applied with

2
Doc/Manual/D.html
View file

@ -280,7 +280,7 @@ class SomeClass : AnInterface, AnotherInterface {
...
}
</pre></div>
<p>For this to work, <tt>AnInterface</tt> and <tt>AnotherInterface</tt> have to be in scope. If SWIG is not in split proxy mode, this is already the case, but it it is, they have to be added to the import list via the <tt>dimports</tt> typemap. Additionally, the import statement depends on the package SWIG is configured to emit the modules to.</p>
<p>For this to work, <tt>AnInterface</tt> and <tt>AnotherInterface</tt> have to be in scope. If SWIG is not in split proxy mode, this is already the case, but if it is, they have to be added to the import list via the <tt>dimports</tt> typemap. Additionally, the import statement depends on the package SWIG is configured to emit the modules to.</p>
<p>The <tt>$importtype</tt> macro helps you to elegantly solve this problem:</p>
<div class="code"><pre>
%typemap(dimports) RemoteMpe %{

64
Doc/Manual/Extending.html
View file

@ -729,7 +729,7 @@ For instance, the following example uses <tt>%rename</tt> in reverse to generate
<div class="code">
<pre>
%rename(foo) foo_i(int);
%rename(foo) foo_d(double;
%rename(foo) foo_d(double);
void foo_i(int);
void foo_d(double);
@ -1576,7 +1576,7 @@ return the node for the first class member.
<div class="indent">
Returns the last child node. You might use this if you wanted to append a new
node to the of a class.
node to the children of a class.
</div>
<p>
@ -2592,36 +2592,36 @@ command line options, simply use code similar to this:
<pre>
void Language::main(int argc, char *argv[]) {
for (int i = 1; i &lt; argc; i++) {
if (argv[i]) {
if (strcmp(argv[i], "-interface") == 0) {
if (argv[i+1]) {
interface = NewString(argv[i+1]);
Swig_mark_arg(i);
Swig_mark_arg(i+1);
i++;
} else {
Swig_arg_error();
}
} else if (strcmp(argv[i], "-globals") == 0) {
if (argv[i+1]) {
global_name = NewString(argv[i+1]);
Swig_mark_arg(i);
Swig_mark_arg(i+1);
i++;
} else {
Swig_arg_error();
}
} else if ((strcmp(argv[i], "-proxy") == 0)) {
proxy_flag = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-keyword") == 0) {
use_kw = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-help") == 0) {
fputs(usage, stderr);
}
...
if (argv[i]) {
if (strcmp(argv[i], "-interface") == 0) {
if (argv[i+1]) {
interface = NewString(argv[i+1]);
Swig_mark_arg(i);
Swig_mark_arg(i+1);
i++;
} else {
Swig_arg_error();
}
} else if (strcmp(argv[i], "-globals") == 0) {
if (argv[i+1]) {
global_name = NewString(argv[i+1]);
Swig_mark_arg(i);
Swig_mark_arg(i+1);
i++;
} else {
Swig_arg_error();
}
} else if ((strcmp(argv[i], "-proxy") == 0)) {
proxy_flag = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-keyword") == 0) {
use_kw = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-help") == 0) {
fputs(usage, stderr);
}
...
}
}
}
</pre>
@ -3164,7 +3164,7 @@ these kinds of problems.
</p>
<dt> <b>Examples/Makefile.in</b>
<dd> Nothing special here; see comments at top the of this file
<dd> Nothing special here; see comments at the top of this file
and look to the existing languages for examples.
<dt> <b>Examples/qux99/check.list</b>

4
Doc/Manual/Go.html
View file

@ -639,12 +639,12 @@ public:
virtual ~FooBarAbstract() {};
std::string FooBar() {
return this->Foo() + ", " + this->Bar();
return this-&gt;Foo() + ", " + this-&gt;Bar();
};
protected:
virtual std::string Foo() {
return "Foo";
return "Foo";
};
virtual std::string Bar() = 0;

49
Doc/Manual/Java.html
View file

@ -3923,12 +3923,24 @@ is used in the feature code. Consider the following, which also happens to be th
if ($error) {
jenv-&gt;ExceptionClear();
$directorthrowshandlers
throw Swig::DirectorException(jenv, $error);
Swig::DirectorException::raise(jenv, $error);
}
%}
</pre>
</div>
<p>
where <tt>Swig::DirectorException::raise</tt> is a helper method in the DirectorException class to throw a C++ exception (implemented in director.swg):
</p>
<div class="code">
<pre>
static void raise(JNIEnv *jenv, jthrowable throwable) {
throw DirectorException(jenv, throwable);
}
</pre>
</div>
<p>The code generated using the <code>director:except</code> feature
replaces the <code>$directorthrowshandlers</code> special variable with the code in
the "directorthrows" typemaps, for each and every exception defined for the method.
@ -3963,7 +3975,7 @@ if (swigerror) {
throw std::out_of_range(Swig::JavaExceptionMessage(jenv, swigerror).message());
}
throw Swig::DirectorException(jenv, swigerror);
Swig::DirectorException::raise(jenv, swigerror);
}
</pre>
</div>
@ -4093,7 +4105,7 @@ the exception specification or <code>%catches</code> feature.
</p>
<p>Note that the "directorthrows" typemaps are important
only if it is important for the the exceptions passed through the C++
only if it is important for the exceptions passed through the C++
layer to be mapped to distinct C++ exceptions. If director methods
are being called by C++ code that is itself wrapped in a
SWIG generated Java wrapper and access is always through this wrapper,
@ -4323,16 +4335,16 @@ struct Vector {
%extend Vector {
char *toString() {
static char tmp[1024];
sprintf(tmp, "Vector(%g, %g, %g)", $self-&gt;x, $self-&gt;y, $self-&gt;z);
return tmp;
static char tmp[1024];
sprintf(tmp, "Vector(%g, %g, %g)", $self-&gt;x, $self-&gt;y, $self-&gt;z);
return tmp;
}
Vector(double x, double y, double z) {
Vector *v = (Vector *) malloc(sizeof(Vector));
v-&gt;x = x;
v-&gt;y = y;
v-&gt;z = z;
return v;
Vector *v = (Vector *) malloc(sizeof(Vector));
v-&gt;x = x;
v-&gt;y = y;
v-&gt;z = z;
return v;
}
};
</pre>
@ -5266,7 +5278,7 @@ void * operator new(size_t t) {
throw bad_alloc();
pJalloc-&gt;ref = 0;
return static_cast&lt;void *&gt;(
static_cast&lt;char *&gt;(static_cast&lt;void *&gt;(pJalloc)) + sizeof(Jalloc));
static_cast&lt;char *&gt;(static_cast&lt;void *&gt;(pJalloc)) + sizeof(Jalloc));
}
}
@ -5681,6 +5693,17 @@ The most important of these implement the mapping of C/C++ types to Java types:
In other words the typemap provides the conversion from the native method call return type. </td>
</tr>
<tr>
<td>jboxtype</td>
<td>Java boxed type.
These are Java code typemaps to provide the Java boxed type, such as, <tt>Integer</tt> for C type <tt>int</tt>.
As autoboxing is only relevant to the Java primitive types, these are only provided for the
C types that map to Java primitive types.
This typemap is usually only used by C++ STL container wrappers that are wrapped by Java generic
types as the boxed type must be used instead of the unboxed/primitive type when declaring a Java generic type.
</td>
</tr>
<tr>
<td>javadirectorin</td>
<td>Conversion from jtype to jstype for director methods.
@ -7217,7 +7240,7 @@ public class runme {
example.print_args(animals);
String args[] = example.get_args();
for (int i=0; i&lt;args.length; i++)
System.out.println(i + ":" + args[i]);
System.out.println(i + ":" + args[i]);
}
}
</pre></div>

94
Doc/Manual/Library.html
View file

@ -12,26 +12,32 @@
<div class="sectiontoc">
<ul>
<li><a href="#Library_nn2">The %include directive and library search path</a>
<li><a href="#Library_nn3">C Arrays and Pointers</a>
<li><a href="#Library_nn3">C arrays and pointers</a>
<ul>
<li><a href="#Library_nn4">cpointer.i</a>
<li><a href="#Library_carrays">carrays.i</a>
<li><a href="#Library_nn6">cmalloc.i</a>
<li><a href="#Library_nn7">cdata.i</a>
</ul>
<li><a href="#Library_nn8">C String Handling</a>
<li><a href="#Library_nn8">C string handling</a>
<ul>
<li><a href="#Library_nn9">Default string handling</a>
<li><a href="#Library_nn10">Passing binary data</a>
<li><a href="#Library_nn11">Using %newobject to release memory</a>
<li><a href="#Library_nn12">cstring.i</a>
</ul>
<li><a href="#Library_stl_cpp_library">STL/C++ Library</a>
<li><a href="#Library_stl_cpp_library">STL/C++ library</a>
<ul>
<li><a href="#Library_std_string">std::string</a>
<li><a href="#Library_std_vector">std::vector</a>
<li><a href="#Library_stl_exceptions">STL exceptions</a>
<li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
<ul>
<li><a href="#Library_shared_ptr_basics">shared_ptr basics</a>
<li><a href="#Library_shared_ptr_inheritance">shared_ptr and inheritance</a>
<li><a href="#Library_shared_ptr_templates">shared_ptr and templates</a>
<li><a href="#Library_shared_ptr_directors">shared_ptr and directors</a>
</ul>
<li><a href="#Library_std_auto_ptr">auto_ptr smart pointer</a>
</ul>
<li><a href="#Library_nn16">Utility Libraries</a>
@ -92,7 +98,7 @@ Set the environment variable to hold an alternative library directory.
The directories that are searched are displayed when using <tt>-verbose</tt> commandline option.
</p>
<H2><a name="Library_nn3">9.2 C Arrays and Pointers</a></H2>
<H2><a name="Library_nn3">9.2 C arrays and pointers</a></H2>
<p>
@ -411,7 +417,7 @@ void print_array(double x[10]);
Now, in a scripting language, you might write this:
</p>
<div class="code">
<div class="targetlang">
<pre>
a = new_doubleArray(10) # Create an array
for i in range(0, 10):
@ -475,7 +481,7 @@ void print_array(double x[10]);
Allows you to do this:
</p>
<div class="code">
<div class="targetlang">
<pre>
import example
c = example.doubleArray(10) # Create double[10]
@ -761,7 +767,7 @@ char *cdata_<em>name</em>(type* ptr, int nitems)
Clearly they are unsafe.
</p>
<H2><a name="Library_nn8">9.3 C String Handling</a></H2>
<H2><a name="Library_nn8">9.3 C string handling</a></H2>
<p>
@ -801,7 +807,7 @@ target language. In other words, if you were using a language like Tcl,
and you wrote this,
</p>
<div class="code">
<div class="targetlang">
<pre>
% foo Hello
</pre>
@ -852,7 +858,7 @@ size_t parity(char *str, size_t len, size_t initial);
Now, in the target language, you can use binary string data like this:
</p>
<div class="code">
<div class="targetlang">
<pre>
&gt;&gt;&gt; s = "H\x00\x15eg\x09\x20"
&gt;&gt;&gt; parity(s, 0)
@ -1365,7 +1371,7 @@ structure or class instead.
</li>
</ul>
<H2><a name="Library_stl_cpp_library">9.4 STL/C++ Library</a></H2>
<H2><a name="Library_stl_cpp_library">9.4 STL/C++ library</a></H2>
<p>
@ -1385,16 +1391,24 @@ The following table shows which C++ classes are supported and the equivalent SWI
<td><b>SWIG Interface library file</b></td>
</tr>
<tr> <td>std::array (C++11)</td> <td>array</td> <td>std_array.i</td> </tr>
<tr> <td>std::auto_ptr</td> <td>memory</td> <td>std_auto_ptr.i</td> </tr>
<tr> <td>std::complex</td> <td>complex</td> <td>std_complex.i</td> </tr>
<tr> <td>std::deque</td> <td>deque</td> <td>std_deque.i</td> </tr>
<tr> <td>std::list</td> <td>list</td> <td>std_list.i</td> </tr>
<tr> <td>std::map</td> <td>map</td> <td>std_map.i</td> </tr>
<tr> <td>std::multimap (C++11)</td> <td>multimap</td> <td>std_multimap.i</td> </tr>
<tr> <td>std::multiset (C++11)</td> <td>multiset</td> <td>std_multiset.i</td> </tr>
<tr> <td>std::pair</td> <td>utility</td> <td>std_pair.i</td> </tr>
<tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr>
<tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr>
<tr> <td>std::unordered_map (C++11)</td> <td>unordered_map</td> <td>std_unordered_map.i</td> </tr>
<tr> <td>std::unordered_multimap (C++11)</td> <td>unordered_multimap</td> <td>std_unordered_multimap.i</td> </tr>
<tr> <td>std::unordered_multiset (C++11)</td> <td>unordered_multiset</td> <td>std_unordered_multiset.i</td> </tr>
<tr> <td>std::unordered_set (C++11)</td> <td>unordered_set</td> <td>std_unordered_set.i</td> </tr>
<tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
<tr> <td>std::array</td> <td>array (C++11)</td> <td>std_array.i</td> </tr>
<tr> <td>std::shared_ptr</td> <td>shared_ptr (C++11)</td> <td>std_shared_ptr.i</td> </tr>
<tr> <td>std::wstring</td> <td>wstring</td> <td>std_wstring.i</td> </tr>
<tr> <td>std::shared_ptr (C++11)</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
</table>
@ -1720,6 +1734,9 @@ Any thrown STL exceptions will then be gracefully handled instead of causing a c
<H3><a name="Library_std_shared_ptr">9.4.4 shared_ptr smart pointer</a></H3>
<H4><a name="Library_shared_ptr_basics">9.4.4.1 shared_ptr basics</a></H4>
<p>
Some target languages have support for handling the shared_ptr reference counted smart pointer.
This smart pointer is available in the standard C++11 library as <tt>std::shared_ptr</tt>.
@ -1813,8 +1830,11 @@ System.out.println(val1 + " " + val2);
</pre>
</div>
<H4><a name="Library_shared_ptr_inheritance">9.4.4.2 shared_ptr and inheritance</a></H4>
<p>
This shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
The shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
<a href="SWIGPlus.html#SWIGPlus_smart_pointers">smart pointer handling</a>.
The shared_ptr library does not generate extra wrappers, just for smart pointer handling, in addition to the proxy class.
The normal proxy class including inheritance relationships is generated as usual.
@ -1892,7 +1912,7 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
<div class="code">
<pre>
%include "boost_shared_ptr.i"
%include &lt;boost_shared_ptr.i&gt;
%shared_ptr(GrandParent);
%shared_ptr(Parent);
%shared_ptr(Child);
@ -1901,8 +1921,52 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
</pre>
</div>
<H4><a name="Library_shared_ptr_templates">9.4.4.3 shared_ptr and templates</a></H4>
<p>
<b>Note:</b> There is somewhat limited support for <tt>%shared_ptr</tt> and the director feature
The <tt>%shared_ptr</tt> macro should be used for all the required instantiations
of the template before each of the <tt>%template</tt> instantiations.
For example, consider <tt>number.h</tt> containing the following illustrative template:
</p>
<div class="code">
<pre>
#include &lt;memory&gt;
template&lt;int N&gt; struct Number {
int num;
Number() : num(N) {}
static std::shared_ptr&lt;Number&lt;N&gt;&gt; make() { return std::make_shared&lt;Number&lt;N&gt;&gt;(); }
};
</pre>
</div>
<p>
The SWIG code below shows the required ordering:
</p>
<div class="code">
<pre>
%include &lt;std_shared_ptr.i&gt;
%shared_ptr(Number&lt;10&gt;);
%shared_ptr(Number&lt;42&gt;);
%{
#include "number.h"
%}
%include "number.h"
%template(Number10) Number&lt;10&gt;;
%template(Number42) Number&lt;42&gt;;
</pre>
</div>
<H4><a name="Library_shared_ptr_directors">9.4.4.4 shared_ptr and directors</a></H4>
<p>
There is somewhat limited support for <tt>%shared_ptr</tt> and the director feature
and the degrees of success varies among the different target languages.
Please help to improve this support by providing patches with improvements.
</p>

14
Doc/Manual/Lisp.html
View file

@ -122,9 +122,12 @@ swig -cffi -help
<H3><a name="Lisp_nn5">27.2.2 Generating CFFI bindings</a></H3>
<p>
As we mentioned earlier the ideal way to use SWIG is to use interface
files. To illustrate the use of it, let's assume that we have a
file named <i>test.h</i> with the following C code:
</p>
<div class="code"><pre>
#define y 5
@ -155,7 +158,10 @@ void lispsort_double (int n, double * array);
enum color { RED, BLUE, GREEN};
</pre></div>
<p>
Corresponding to this we will write a simple interface file:
</p>
<div class="code"><pre>
%module test
@ -163,7 +169,9 @@ Corresponding to this we will write a simple interface file:
</pre></div>
<p>
The generated SWIG Code will be:
</p>
<div class="targetlang"><pre>
;;;SWIG wrapper code starts here
@ -430,8 +438,10 @@ Also, while parsing the C++ file and generating C wrapper code SWIG
%include "target/header.h"
</pre></div>
<p>
Various features which were available for C headers can also be used
here. The target header which we are going to use here is:
</p>
<div class="code"><pre>
namespace OpenDemo {
class Test
@ -478,8 +488,10 @@ namespace OpenDemo {
%include "test.cpp"
</pre></div>
<p>
SWIG generates 3 files, the first one is a C wrap which we don't show,
the second is the plain CFFI wrapper which is as shown below:
</p>
<div class="targetlang"><pre>
(cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void
(self :pointer)
@ -528,11 +540,13 @@ SWIG generates 3 files, the first one is a C wrap which we don't show,
(cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer)
</pre></div>
<p>
The output is pretty good but it fails in disambiguating overloaded
functions such as the constructor, in this case. One way of
resolving this problem is to make the interface use the rename
directiv, but hopefully there are better solutions.
In addition SWIG also generates, a CLOS file
</p>
<div class="targetlang"><pre>

18
Doc/Manual/Lua.html
View file

@ -1008,11 +1008,10 @@ The following operators cannot be overloaded (mainly because they are not suppor
<p>
SWIG also accepts the <tt>__str__()</tt> member function which converts an object to a string. This function should return a const char*, preferably to static memory. This will be used for the <tt>print()</tt> and <tt>tostring()</tt> functions in Lua. Assuming the complex class has a function
</p>
<div class="code"><pre>const char* __str__()
{
static char buffer[255];
sprintf(buffer, "Complex(%g, %g)", this-&gt;re(), this-&gt;im());
return buffer;
<div class="code"><pre>const char* __str__() {
static char buffer[255];
sprintf(buffer, "Complex(%g, %g)", this-&gt;re(), this-&gt;im());
return buffer;
}
</pre></div>
<p>
@ -1031,11 +1030,10 @@ Complex(10, 12)
<p>
It is also possible to overload the operator<tt>[]</tt>, but currently this cannot be automatically performed. To overload the operator<tt>[]</tt> you need to provide two functions, <tt>__getitem__()</tt> and <tt>__setitem__()</tt>
</p>
<div class="code"><pre>class Complex
{
//....
double __getitem__(int i)const; // i is the index, returns the data
void __setitem__(int i, double d); // i is the index, d is the data
<div class="code"><pre>class Complex {
//....
double __getitem__(int i)const; // i is the index, returns the data
void __setitem__(int i, double d); // i is the index, d is the data
};
</pre></div>
<p>

125
Doc/Manual/Perl5.html
View file

@ -949,7 +949,7 @@ Foo *BarToFoo(Bar *b) {
}
Foo *IncrFoo(Foo *f, int i) {
return f+i;
return f+i;
}
%}
</pre>
@ -1057,7 +1057,7 @@ produces a single accessor function like this:
<div class="code">
<pre>
int *Foo_x_get(Foo *self) {
return self-&gt;x;
return self-&gt;x;
};
</pre>
</div>
@ -1092,11 +1092,11 @@ generates accessor functions such as this:
<div class="code">
<pre>
Foo *Bar_f_get(Bar *b) {
return &amp;b-&gt;f;
return &amp;b-&gt;f;
}
void Bar_f_set(Bar *b, Foo *val) {
b-&gt;f = *val;
b-&gt;f = *val;
}
</pre>
</div>
@ -1633,9 +1633,8 @@ class DoubleArray {
void setitem(int i, double val) {
if ((i &gt;= 0) &amp;&amp; (i &lt; n))
ptr[i] = val;
else {
else
throw RangeError();
}
}
};
</pre></div>
@ -1888,9 +1887,9 @@ like this:
<div class="targetlang">
<pre>
%typemap(out) int {
$result = sv_newmortal();
set_setiv($result, (IV) $1);
argvi++;
$result = sv_newmortal();
set_setiv($result, (IV) $1);
argvi++;
}
</pre>
</div>
@ -2313,8 +2312,8 @@ Consider the following data structure:
<div class="code"><pre>
#define SIZE 8
typedef struct {
int values[SIZE];
...
int values[SIZE];
...
} Foo;
</pre></div>
@ -2328,10 +2327,10 @@ To make the member writable, a "memberin" typemap can be used.
<div class="code"><pre>
%typemap(memberin) int [SIZE] {
int i;
for (i = 0; i &lt; SIZE; i++) {
$1[i] = $input[i];
}
int i;
for (i = 0; i &lt; SIZE; i++) {
$1[i] = $input[i];
}
}
</pre></div>
@ -2600,48 +2599,48 @@ package example::Vector;
%BLESSEDMEMBERS = ();
sub new () {
my $self = shift;
my @args = @_;
$self = vectorc::new_Vector(@args);
return undef if (!defined($self));
bless $self, "example::Vector";
$OWNER{$self} = 1;
my %retval;
tie %retval, "example::Vector", $self;
return bless \%retval, "Vector";
my $self = shift;
my @args = @_;
$self = vectorc::new_Vector(@args);
return undef if (!defined($self));
bless $self, "example::Vector";
$OWNER{$self} = 1;
my %retval;
tie %retval, "example::Vector", $self;
return bless \%retval, "Vector";
}
sub DESTROY {
return unless $_[0]-&gt;isa('HASH');
my $self = tied(%{$_[0]});
delete $ITERATORS{$self};
if (exists $OWNER{$self}) {
examplec::delete_Vector($self));
delete $OWNER{$self};
}
return unless $_[0]-&gt;isa('HASH');
my $self = tied(%{$_[0]});
delete $ITERATORS{$self};
if (exists $OWNER{$self}) {
examplec::delete_Vector($self));
delete $OWNER{$self};
}
}
sub FETCH {
my ($self, $field) = @_;
my $member_func = "vectorc::Vector_${field}_get";
my $val = &amp;$member_func($self);
if (exists $BLESSEDMEMBERS{$field}) {
return undef if (!defined($val));
my %retval;
tie %retval, $BLESSEDMEMBERS{$field}, $val;
return bless \%retval, $BLESSEDMEMBERS{$field};
}
return $val;
my ($self, $field) = @_;
my $member_func = "vectorc::Vector_${field}_get";
my $val = &amp;$member_func($self);
if (exists $BLESSEDMEMBERS{$field}) {
return undef if (!defined($val));
my %retval;
tie %retval, $BLESSEDMEMBERS{$field}, $val;
return bless \%retval, $BLESSEDMEMBERS{$field};
}
return $val;
}
sub STORE {
my ($self, $field, $newval) = @_;
my $member_func = "vectorc::Vector_${field}_set";
if (exists $BLESSEDMEMBERS{$field}) {
&amp;$member_func($self, tied(%{$newval}));
} else {
&amp;$member_func($self, $newval);
}
my ($self, $field, $newval) = @_;
my $member_func = "vectorc::Vector_${field}_set";
if (exists $BLESSEDMEMBERS{$field}) {
&amp;$member_func($self, tied(%{$newval}));
} else {
&amp;$member_func($self, $newval);
}
}
</pre></div>
@ -2842,11 +2841,11 @@ this:
<div class="targetlang"><pre>
sub dot_product {
my @args = @_;
$args[0] = tied(%{$args[0]}); # Get the real pointer values
$args[1] = tied(%{$args[1]});
my $result = vectorc::dot_product(@args);
return $result;
my @args = @_;
$args[0] = tied(%{$args[0]}); # Get the real pointer values
$args[1] = tied(%{$args[1]});
my $result = vectorc::dot_product(@args);
return $result;
}
</pre></div>
@ -2985,7 +2984,7 @@ sub set_transform
for (my $j = 0; $j &lt; 4, $j++)
{
mat44_set($a, $i, $j, $x-&gt;[i][j])
}
}
}
example.set_transform($im, $a);
free_mat44($a);
@ -3104,14 +3103,14 @@ the methods one() and two() (but not three()):
%feature("director") Foo;
class Foo {
public:
Foo(int foo);
virtual void one();
virtual void two();
Foo(int foo);
virtual void one();
virtual void two();
};
class Bar: public Foo {
public:
virtual void three();
virtual void three();
};
</pre>
</div>
@ -3279,9 +3278,9 @@ suffice in most cases:
<div class="code">
<pre>
%feature("director:except") {
if ($error != NULL) {
throw Swig::DirectorMethodException();
}
if ($error != NULL) {
throw Swig::DirectorMethodException();
}
}
</pre>
</div>
@ -3305,8 +3304,8 @@ suitable exception handler:
<div class="code">
<pre>
%exception {
try { $action }
catch (Swig::DirectorException &amp;e) { SWIG_fail; }
try { $action }
catch (Swig::DirectorException &amp;e) { SWIG_fail; }
}
</pre>
</div>

38
Doc/Manual/Php.html
View file

@ -163,7 +163,7 @@ If the module is in PHP's default extension directory, you can omit the path.
<p>
For some SAPIs (for example, the CLI SAPI) you can instead use the
<a href="http://php.net/manual/en/function.dl.php">dl() function</a> to load
an extension at run time, by adding a like like this to the start of each
an extension at run time, by adding a line like this to the start of each
PHP script which uses your extension:
</p>
@ -390,8 +390,7 @@ Although PHP does not support overloading functions natively, swig
will generate dispatch functions which will use <tt>%typecheck</tt>
typemaps to allow overloading. This dispatch function's operation and
precedence is described in <a
href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
Overloaded Functions and Methods</a>.
href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>.
</p>
<!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality
@ -820,6 +819,15 @@ Results in the following in "example.php"
echo "example.php execution\n";
</pre></div>
<p>
The <b>version</b> pragma can be used to add version to generated PHP extension module. The version is inserted in the zend_module_entry block.
</p>
<div class="code"><pre>
%module example
%pragma(php) version="1.5"
</pre></div>
<p>
The <b>include</b> pragma is a short cut to add include statements to
the example.php file.
@ -977,14 +985,14 @@ the methods one() and two() (but not three()):
%feature("director") Foo;
class Foo {
public:
Foo(int foo);
virtual void one();
virtual void two();
Foo(int foo);
virtual void one();
virtual void two();
};
class Bar: public Foo {
public:
virtual void three();
virtual void three();
};
</pre>
</div>
@ -1116,12 +1124,12 @@ Here is an example:
<pre>
class Foo {
public:
...
...
};
class FooContainer {
public:
void addFoo(Foo *);
...
void addFoo(Foo *);
...
};
</pre>
</div>
@ -1166,9 +1174,9 @@ should suffice in most cases:
<div class="code">
<pre>
%feature("director:except") {
if ($error == FAILURE) {
throw Swig::DirectorMethodException();
}
if ($error == FAILURE) {
throw Swig::DirectorMethodException();
}
}
</pre>
</div>
@ -1195,8 +1203,8 @@ suitable exception handler:
<div class="code">
<pre>
%exception {
try { $action }
catch (Swig::DirectorException &amp;e) { SWIG_fail; }
try { $action }
catch (Swig::DirectorException &amp;e) { SWIG_fail; }
}
</pre>
</div>

4
Doc/Manual/Pike.html
View file

@ -230,8 +230,8 @@ For example, given this C++ class declaration:
class Shape
{
public:
static void print();
static int nshapes;
static void print();
static int nshapes;
};
</pre></div>

456
Doc/Manual/Python.html
View file

File diff suppressed because it is too large Load diff

2
Doc/Manual/R.html
View file

@ -129,7 +129,7 @@ These two files can be loaded in any order
<li>If you do not set the output file name appropriately, you might see errors like
<div class="shell">
<pre>
> fact(4)
&gt; fact(4)
Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") :
"R_swig_fact" not available for .Call() for package "example"
</pre>

91
Doc/Manual/SWIG.html
View file

@ -389,7 +389,7 @@ For example
/* bar not wrapped unless foo has been defined and
the declaration of bar within foo has already been parsed */
int foo::bar(int) {
... whatever ...
... whatever ...
}
</pre>
</div>
@ -1043,14 +1043,14 @@ expect :</p>
<div class="targetlang"><pre>
# Copy a file
def filecopy(source, target):
f1 = fopen(source, "r")
f2 = fopen(target, "w")
buffer = malloc(8192)
nbytes = fread(buffer, 8192, 1, f1)
while (nbytes &gt; 0):
fwrite(buffer, 8192, 1, f2)
nbytes = fread(buffer, 8192, 1, f1)
free(buffer)
f1 = fopen(source, "r")
f2 = fopen(target, "w")
buffer = malloc(8192)
nbytes = fread(buffer, 8192, 1, f1)
while (nbytes &gt; 0):
fwrite(buffer, 8192, 1, f2)
nbytes = fread(buffer, 8192, 1, f1)
free(buffer)
</pre></div>
<p>
@ -1236,9 +1236,9 @@ creating a wrapper equivalent to the following:
<div class="code"><pre>
double wrap_dot_product(Vector *a, Vector *b) {
Vector x = *a;
Vector y = *b;
return dot_product(x, y);
Vector x = *a;
Vector y = *b;
return dot_product(x, y);
}
</pre></div>
@ -1266,12 +1266,12 @@ pointers. As a result, SWIG creates a wrapper like this:
<div class="code"><pre>
Vector *wrap_cross_product(Vector *v1, Vector *v2) {
Vector x = *v1;
Vector y = *v2;
Vector *result;
result = (Vector *) malloc(sizeof(Vector));
*(result) = cross(x, y);
return result;
Vector x = *v1;
Vector y = *v2;
Vector *result;
result = (Vector *) malloc(sizeof(Vector));
*(result) = cross(x, y);
return result;
}
</pre></div>
@ -1280,10 +1280,10 @@ or if SWIG was run with the <tt>-c++</tt> option:</p>
<div class="code"><pre>
Vector *wrap_cross(Vector *v1, Vector *v2) {
Vector x = *v1;
Vector y = *v2;
Vector *result = new Vector(cross(x, y)); // Uses default copy constructor
return result;
Vector x = *v1;
Vector y = *v2;
Vector *result = new Vector(cross(x, y)); // Uses default copy constructor
return result;
}
</pre></div>
@ -1736,6 +1736,16 @@ already defined in the target scripting language. However, if you are
careful about namespaces and your use of modules, you can usually
avoid these problems.</p>
<p>
When wrapping C code, simple use of identifiers/symbols with <tt>%rename</tt> usually suffices.
When wrapping C++ code, simple use of simple identifiers/symbols with <tt>%rename</tt> might be too
limiting when using C++ features such as function overloading, default arguments, namespaces, template specialization etc.
If you are using the <tt>%rename</tt> directive and C++, make sure you read the
<a href="SWIGPlus.html">SWIG and C++</a> chapter and in particular the section on
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
for method overloading and default arguments.
</p>
<p>
Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive. <tt>%ignore</tt> instructs SWIG
to ignore declarations that match a given identifier. For example:
@ -2078,7 +2088,7 @@ except those consisting of capital letters only:
<p>
Finally, variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help
wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> section in the C++ chapter.
</p>
@ -2368,10 +2378,10 @@ defined in the interface. For example:
<div class="code"><pre>
struct Vector *new_Vector() {
return (Vector *) calloc(1, sizeof(struct Vector));
return (Vector *) calloc(1, sizeof(struct Vector));
}
void delete_Vector(struct Vector *obj) {
free(obj);
free(obj);
}
</pre>
</div>
@ -2602,10 +2612,10 @@ like this:
<div class="code">
<pre>
WORD Foo_w_get(Foo *f) {
return f-&gt;w;
return f-&gt;w;
}
void Foo_w_set(FOO *f, WORD value) {
f-&gt;w = value;
f-&gt;w = value;
}
</pre>
</div>
@ -2896,7 +2906,7 @@ instead of a method. To do this, you might write some code like this:
<pre>
// Add a new attribute to Vector
%extend Vector {
const double magnitude;
const double magnitude;
}
// Now supply the implementation of the Vector_magnitude_get function
%{
@ -3293,11 +3303,27 @@ Vector *new_Vector() {
return (Vector *) malloc(sizeof(Vector));
}
%}
</pre></div>
<p>
The <tt>%inline</tt> directive inserts all of the code that follows
This is the same as writing:
</p>
<div class="code"><pre>
%{
/* Create a new vector */
Vector *new_Vector() {
return (Vector *) malloc(sizeof(Vector));
}
%}
/* Create a new vector */
Vector *new_Vector() {
return (Vector *) malloc(sizeof(Vector));
}
</pre></div>
<p>
In other words, the <tt>%inline</tt> directive inserts all of the code that follows
verbatim into the header portion of an interface file. The code is
then parsed by both the SWIG preprocessor and parser.
Thus, the above example creates a new command <tt>new_Vector</tt> using only one
@ -3305,6 +3331,11 @@ declaration. Since the code inside an <tt>%inline %{ ... %}</tt> block
is given to both the C compiler and SWIG, it is illegal to include any
SWIG directives inside a <tt>%{ ... %}</tt> block.</p>
<p>
<b>Note:</b> The usual SWIG C preprocessor rules apply to code in <tt>%apply</tt> blocks when SWIG parses this code. For example, as mentioned earlier, <a href="SWIG.html#SWIG_nn6">SWIG's C Preprocessor</a> does not follow <tt>#include</tt> directives by default.
</p>
<H3><a name="SWIG_nn44">5.6.4 Initialization blocks</a></H3>

883
Doc/Manual/SWIGPlus.html
View file

File diff suppressed because it is too large Load diff

51
Doc/Manual/Scilab.html
View file

@ -121,15 +121,15 @@ In this example we bind from C a function and a global variable into Scilab. The
double Foo = 3.0;
int fact(int n) {
if (n &lt; 0) {
return 0;
}
else if (n == 0) {
return 1;
}
else {
return n * fact(n-1);
}
if (n &lt; 0) {
return 0;
}
else if (n == 0) {
return 1;
}
else {
return n * fact(n-1);
}
}
%}
</pre></div>
@ -304,6 +304,11 @@ The following table lists the Scilab specific command line options in addition t
<td>Generate the gateway XML with the given &lt;gateway_id&gt;</td>
</tr>
<tr>
<td><tt>-targetversion</tt></td>
<td>Generate for Scilab target (major) version</td>
</tr>
</table>
<p>
@ -331,13 +336,17 @@ There are a few exceptions, such as constants and enumerations, which can be wra
<p>
In Scilab 5.x, identifier names are composed of 24 characters maximum (this limitation should disappear from Scilab 6.0 onwards).
<br>Thus long function or variable names may be truncated and this can cause ambiguities.
In Scilab 5.x, identifier names are composed of 24 characters maximum (this limitation disappears from Scilab 6.0 onwards).
<br>By default, variable, member, and function names longer than 24 charaters are truncated, and a warning is produced for each truncation.
</p>
<p>This happens especially when wrapping structs/classes, for which the wrapped function name is composed of the struct/class name and field names.
<p>This can cause ambiguities, especially when wrapping structs/classes, for which the wrapped function name is composed of the struct/class name and field names.
In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a> can be used to choose a different Scilab name.
</p>
<p>
Note: truncations can be disabled by specifying the target version 6 of Scilab in the <tt>targetversion</tt> argument (i.e. <tt>-targetversion 6</tt>).
</p>
<H3><a name="Scilab_wrapping_functions">39.3.3 Functions</a></H3>
@ -887,8 +896,8 @@ Let's see it on an example of a struct with two members:
%inline %{
typedef struct {
int x;
int arr[4];
int x;
int arr[4];
} Foo;
%}
@ -1124,21 +1133,21 @@ But we can use either use the <tt>get_perimeter()</tt> function of the parent cl
<p>
As explained in <a href="SWIGPlus.html#SWIGPlus_overloaded_methods">6.15</a> SWIG provides support for overloaded functions and constructors.
As explained in <a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a> SWIG provides support for overloaded functions and constructors.
</p>
<p>As SWIG knows pointer types, the overloading works also with pointer types, here is is an example with a function <tt>magnify</tt> overloaded for the previous classes <tt>Shape</tt> and <tt>Circle</tt>:
<p>As SWIG knows pointer types, the overloading works also with pointer types, here is an example with a function <tt>magnify</tt> overloaded for the previous classes <tt>Shape</tt> and <tt>Circle</tt>:
</p>
<div class="code"><pre>
%module example
void magnify(Square *square, double factor) {
square-&gt;size *= factor;
square-&gt;size *= factor;
};
void magnify(Circle *circle, double factor) {
square-&gt;radius *= factor;
square-&gt;radius *= factor;
};
</pre></div>
@ -1611,11 +1620,11 @@ void printArray(int values[], int len) {
<p>
There are no specific typemaps for pointer-to-pointers, they are are mapped as pointers in Scilab.
There are no specific typemaps for pointer-to-pointers, they are mapped as pointers in Scilab.
</p>
<p>
Pointer-to-pointers are sometimes used to implement matrices in C. The following is a an example of this:
Pointer-to-pointers are sometimes used to implement matrices in C. The following is an example of this:
</p>
@ -2053,7 +2062,7 @@ In this mode, the following SWIG options may be used to setup the build:
Let's give an example how to build a module <tt>example</tt>, composed of two sources, and using a library dependency:
</p>
<ul>
<li>the sources are <tt>baa1.c</tt> and <tt>baa2.c</tt> (and are stored in in the current directory)</li>
<li>the sources are <tt>baa1.c</tt> and <tt>baa2.c</tt> (and are stored in the current directory)</li>
<li>the library is <tt>libfoo</tt> in <tt>/opt/foo</tt> (headers stored in <tt>/opt/foo/include</tt>, and shared library in <tt>/opt/foo/lib</tt>)</li>
</ul>

6
Doc/Manual/Sections.html
View file

@ -1,14 +1,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG-3.0 Documentation</title>
<title>SWIG-4.0 Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Sections">SWIG-3.0 Documentation</a></H1>
<H1><a name="Sections">SWIG-4.0 Documentation</a></H1>
<p>
Last update : SWIG-3.0.13 (in progress)
Last update : SWIG-4.0.0 (in progress)
</p>
<H2><a name="Sections_Sections">Sections</a></H2>

62
Doc/Manual/Tcl.html
View file

@ -958,7 +958,7 @@ Foo *BarToFoo(Bar *b) {
}
Foo *IncrFoo(Foo *f, int i) {
return f+i;
return f+i;
}
%}
</pre>
@ -1054,7 +1054,7 @@ example, consider this:
<div class="code">
<pre>
struct Bar {
int x[16];
int x[16];
};
</pre>
</div>
@ -1456,9 +1456,9 @@ Similarly, if you have a class like this,
<pre>
class Foo {
public:
Foo();
Foo(const Foo &amp;);
...
Foo();
Foo(const Foo &amp;);
...
};
</pre>
</div>
@ -1693,11 +1693,11 @@ For example:
%rename(Bar_spam) Bar::spam;
namespace Foo {
int spam();
int spam();
}
namespace Bar {
int spam();
int spam();
}
</pre>
</div>
@ -1886,19 +1886,19 @@ then SWIG transforms it into a set of low-level procedural wrappers. For example
<div class="code">
<pre>
Foo *new_Foo() {
return new Foo();
return new Foo();
}
void delete_Foo(Foo *f) {
delete f;
delete f;
}
int Foo_x_get(Foo *f) {
return f-&gt;x;
return f-&gt;x;
}
void Foo_x_set(Foo *f, int value) {
f-&gt;x = value;
f-&gt;x = value;
}
int Foo_spam(Foo *f, int arg1) {
return f-&gt;spam(arg1);
return f-&gt;spam(arg1);
}
</pre>
</div>
@ -1945,8 +1945,8 @@ ownership of the result. For example:
<pre>
class Foo {
public:
Foo();
Foo bar();
Foo();
Foo bar();
};
</pre>
</div>
@ -1975,9 +1975,9 @@ they came from. Therefore, the ownership is set to zero. For example:
<pre>
class Foo {
public:
...
Foo *spam();
...
...
Foo *spam();
...
};
</pre>
</div>
@ -2011,8 +2011,8 @@ or global variable. For example, consider this interface:
%module example
struct Foo {
int value;
Foo *next;
int value;
Foo *next;
};
Foo *head = 0;
@ -2465,9 +2465,9 @@ you might define a typemap like this:
%module example
%typemap(in) int {
if (Tcl_GetIntFromObj(interp, $input, &amp;$1) == TCL_ERROR)
return TCL_ERROR;
printf("Received an integer : %d\n", $1);
if (Tcl_GetIntFromObj(interp, $input, &amp;$1) == TCL_ERROR)
return TCL_ERROR;
printf("Received an integer : %d\n", $1);
}
%inline %{
extern int fact(int n);
@ -2585,7 +2585,7 @@ like this:
<div class="code">
<pre>
%typemap(out) int {
Tcl_SetObjResult(interp, Tcl_NewIntObj($1));
Tcl_SetObjResult(interp, Tcl_NewIntObj($1));
}
</pre>
</div>
@ -3215,28 +3215,28 @@ helper functions to access arrays :
%inline %{
double *new_double(int size) {
return (double *) malloc(size*sizeof(double));
return (double *) malloc(size*sizeof(double));
}
void delete_double(double *a) {
free(a);
free(a);
}
double get_double(double *a, int index) {
return a[index];
return a[index];
}
void set_double(double *a, int index, double val) {
a[index] = val;
a[index] = val;
}
int *new_int(int size) {
return (int *) malloc(size*sizeof(int));
return (int *) malloc(size*sizeof(int));
}
void delete_int(int *a) {
free(a);
free(a);
}
int get_int(int *a, int index) {
return a[index];
return a[index];
}
int set_int(int *a, int index, int val) {
a[index] = val;
a[index] = val;
}
%}

91
Doc/Manual/Typemaps.html
View file

@ -3904,9 +3904,9 @@ A fragment can use one or more additional fragments, for example:
<div class="code">
<pre>
%fragment("&lt;limits.h&gt;", "header") {
%#include &lt;limits.h&gt;
}
%fragment("&lt;limits.h&gt;", "header") %{
#include &lt;limits.h&gt;
%}
%fragment("AsMyClass", "header", fragment="&lt;limits.h&gt;") {
@ -3989,8 +3989,91 @@ Finally, you can force the inclusion of a fragment at any point in the generated
</div>
<p>
which is very useful inside a template class, for example.
which, for example, is very useful inside a template class.
Another useful case is when using <tt>%extend</tt> inside a class
where the additional code in the <tt>%extend</tt> block depends on the contents of the fragment.
</p>
<div class="code">
<pre>
%fragment("&lt;limits.h&gt;", "header") %{
#include &lt;limits.h&gt;
%}
struct X {
...
%extend {
%fragment("&lt;limits.h&gt;");
bool check(short val) {
if (val &lt; SHRT_MIN /*defined in &lt;limits.h&gt;*/) {
return true;
} else {
return false;
}
}
}
};
</pre>
</div>
<p>
Forced inclusion of fragments can be used as a replacement for <a href="SWIG.html#SWIG_nn42">code insertion block</a>, ensuring the
code block is only generated once.
Consider the contents of FileA.i below which first uses a code insertion block and then a forced fragment inclusion to generate code:
</p>
<div class="code">
<pre>
// FileA.i
%{
#include &lt;stdio.h&gt;
%}
%fragment("&lt;limits.h&gt;");
</pre>
</div>
<p>
and another file including the above:
</p>
<div class="code">
<pre>
// FileB.i
%include "FileA.i"
</pre>
</div>
<p>
The resulting code in the wrappers for FileB.i is:
</p>
<div class="code">
<pre>
#include &lt;stdio.h&gt;
#include &lt;limits.h&gt;
</pre>
</div>
<p>
A note of caution must be mentioned when using <tt>%fragment</tt> forced inclusion or code insertion blocks with <tt>%import</tt>.
If <tt>%import</tt> is used instead:
</p>
<div class="code">
<pre>
// FileC.i
%import "FileA.i"
</pre>
</div>
<p>
then nothing is generated in the resulting code in the wrappers for FileC.i.
This is because <tt>%import</tt> is for collecting type information and does not result in any code
being generated, see <a href="Preprocessor.html#Preprocessor_nn3">File Imports</a>.
</p>
</ol>
<p>

4
Doc/Manual/Varargs.html
View file

@ -423,8 +423,8 @@ Variable length arguments may be used in typemap specifications. For example:
<div class="code">
<pre>
%typemap(in) (...) {
// Get variable length arguments (somehow)
...
// Get variable length arguments (somehow)
...
}
%typemap(in) (const char *fmt, ...) {

4
Doc/Manual/index.html
View file

@ -1,11 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG-3.0 Documentation</title>
<title>SWIG-4.0 Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="index">SWIG-3.0 Documentation</a></H1>
<H1><a name="index">SWIG-4.0 Documentation</a></H1>
The SWIG documentation is available in one of the following formats.
<ul>