Update Octave manual to use "swigexample" instead of "example"
Closes #46
This commit is contained in:
Karl Wette
William S Fulton
parent
c28d0c6c80
commit
95e2142347
1 changed files with 50 additions and 50 deletions
|
|
@ -74,7 +74,7 @@ Let's start with a very simple SWIG interface file, example.i:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%module swigexample
|
||||
%{
|
||||
#include "example.h"
|
||||
%}
|
||||
|
|
@ -143,10 +143,10 @@ $ mkoctfile example_wrap.cpp example.c
|
|||
</p>
|
||||
|
||||
<p>
|
||||
mkoctfile will produce "example.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking
|
||||
mkoctfile will produce "swigexample.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example</pre></div>
|
||||
<div class="targetlang"><pre>octave:1> swigexample</pre></div>
|
||||
|
||||
<H3><a name="Octave_nn6"></a>30.2.3 Using your module</H3>
|
||||
|
||||
|
|
@ -157,13 +157,13 @@ Assuming all goes well, you will be able to do this:
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>$ octave -q
|
||||
octave:1> example
|
||||
octave:2> example.gcd(4,6)
|
||||
octave:1> swigexample
|
||||
octave:2> swigexample.gcd(4,6)
|
||||
ans = 2
|
||||
octave:3> example.cvar.Foo
|
||||
octave:3> swigexample.cvar.Foo
|
||||
ans = 3
|
||||
octave:4> example.cvar.Foo=4;
|
||||
octave:5> example.cvar.Foo
|
||||
octave:4> swigexample.cvar.Foo=4;
|
||||
octave:5> swigexample.cvar.Foo
|
||||
ans = 4 </pre></div>
|
||||
|
||||
<H2><a name="Octave_nn7"></a>30.3 A tour of basic C/C++ wrapping</H2>
|
||||
|
|
@ -173,11 +173,11 @@ ans = 4 </pre></div>
|
|||
|
||||
|
||||
<p>
|
||||
The SWIG module directive specifies the name of the Octave module. If you specify "module example", then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
|
||||
The SWIG module directive specifies the name of the Octave module. If you specify "module swigexample", then in Octave everything in the module will be accessible under "swigexample", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
When Octave is asked to invoke <tt>example</tt>, it will try to find the ".m" or ".oct" file that defines the function "example". You therefore need to make sure that "example.oct" is in Octave's search path, which can be specified with the environment variable "OCTAVE_PATH".
|
||||
When Octave is asked to invoke <tt>swigexample</tt>, it will try to find the ".m" or ".oct" file that defines the function "swigexample". You therefore need to make sure that "swigexample.oct" is in Octave's search path, which can be specified with the environment variable "OCTAVE_PATH".
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -185,7 +185,7 @@ To load an Octave module, simply type its name:
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example;
|
||||
octave:1> swigexample;
|
||||
octave:2> gcd(4,6)
|
||||
ans = 2
|
||||
octave:3> cvar.Foo
|
||||
|
|
@ -202,15 +202,15 @@ If the module is also used in the base context, however, it must first be loaded
|
|||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> function l = my_lcm(a,b)
|
||||
> example
|
||||
> l = abs(a*b)/example.gcd(a,b);
|
||||
> swigexample
|
||||
> l = abs(a*b)/swigexample.gcd(a,b);
|
||||
> endfunction
|
||||
octave:2> my_lcm(4,6)
|
||||
ans = 12
|
||||
octave:3> example.gcd(4,6)
|
||||
octave:3> swigexample.gcd(4,6)
|
||||
error: can't perform indexing operations for <unknown type> type
|
||||
octave:3> example;
|
||||
octave:4> example.gcd(4,6)
|
||||
octave:3> swigexample;
|
||||
octave:4> swigexample.gcd(4,6)
|
||||
ans = 2
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -221,14 +221,14 @@ ans = 2
|
|||
Global functions are wrapped as new Octave built-in functions. For example,
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
int fact(int n); </pre></div>
|
||||
|
||||
<p>
|
||||
creates a built-in function <tt>example.fact(n)</tt> that works exactly like you think it does:
|
||||
creates a built-in function <tt>swigexample.fact(n)</tt> that works exactly like you think it does:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example.fact(4)
|
||||
<div class="targetlang"><pre>octave:1> swigexample.fact(4)
|
||||
24 </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn10"></a>30.3.3 Global variables</H3>
|
||||
|
|
@ -238,7 +238,7 @@ int fact(int n); </pre></div>
|
|||
Global variables are a little special in Octave. Given a global variable:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
extern double Foo;
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -246,20 +246,20 @@ extern double Foo;
|
|||
To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_set would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variables onto the C variable.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> c=example.cvar.Foo
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> c=swigexample.cvar.Foo
|
||||
c = 3
|
||||
octave:3> example.cvar.Foo=4;
|
||||
octave:3> swigexample.cvar.Foo=4;
|
||||
octave:4> c
|
||||
c = 3
|
||||
octave:5> example.cvar.Foo
|
||||
octave:5> swigexample.cvar.Foo
|
||||
ans = 4</pre></div>
|
||||
|
||||
<p>
|
||||
If a variable is marked with the %immutable directive then any attempts to set this variable will cause an Octave error. Given a global variable:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%immutable;
|
||||
extern double Foo;
|
||||
%mutable;
|
||||
|
|
@ -269,8 +269,8 @@ extern double Foo;
|
|||
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example
|
||||
octave:2> example.Foo=4
|
||||
<div class="targetlang"><pre>octave:1> swigexample
|
||||
octave:2> swigexample.Foo=4
|
||||
error: attempt to set immutable member variable
|
||||
error: assignment failed, or no method for `swig_type = scalar'
|
||||
error: evaluating assignment expression near line 2, column 12 </pre></div>
|
||||
|
|
@ -279,9 +279,9 @@ error: evaluating assignment expression near line 2, column 12 </pre></div>
|
|||
It is possible to add new functions or variables to the module. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> example.PI=3.142;
|
||||
octave:3> example.PI
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> swigexample.PI=3.142;
|
||||
octave:3> swigexample.PI
|
||||
ans = 3.1420 </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn11"></a>30.3.4 Constants and enums</H3>
|
||||
|
|
@ -291,7 +291,7 @@ ans = 3.1420 </pre></div>
|
|||
Because Octave doesn't really have the concept of constants, C/C++ constants are not really constant in Octave. They are actually just a copy of the value into the Octave interpreter. Therefore they can be changed just as any other value. For example given some constants:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%constant int ICONST=42;
|
||||
#define SCONST "Hello World"
|
||||
enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
|
||||
|
|
@ -301,9 +301,9 @@ enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
|
|||
This is 'effectively' converted into the following Octave code:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>example.ICONST=42
|
||||
example.SCONST="Hello World"
|
||||
example.SUNDAY=0
|
||||
<div class="targetlang"><pre>swigexample.ICONST=42
|
||||
swigexample.SCONST="Hello World"
|
||||
swigexample.SUNDAY=0
|
||||
.... </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn12"></a>30.3.5 Pointers</H3>
|
||||
|
|
@ -314,7 +314,7 @@ example.SUNDAY=0
|
|||
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
FILE *fopen(const char *filename, const char *mode);
|
||||
int fputs(const char *, FILE *);
|
||||
int fclose(FILE *);
|
||||
|
|
@ -325,18 +325,18 @@ When wrapped, you will be able to use the functions in a natural way from Octave
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example;
|
||||
octave:2> f=example.fopen("w","junk");
|
||||
octave:3> example.fputs("Hello world",f);
|
||||
octave:4> example.fclose(f);
|
||||
octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("w","junk");
|
||||
octave:3> swigexample.fputs("Hello world",f);
|
||||
octave:4> swigexample.fclose(f);
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Simply printing the value of a wrapped C++ type will print it's typename. E.g.,
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> f=example.fopen("junk","w");
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("junk","w");
|
||||
octave:3> f
|
||||
f =
|
||||
|
||||
|
|
@ -348,8 +348,8 @@ f =
|
|||
As the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes and structs (see below).
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> f=example.fopen("not there","r");
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("not there","r");
|
||||
error: value on right hand side of assignment is undefined
|
||||
error: evaluating assignment expression near line 2, column 2 </pre></div>
|
||||
|
||||
|
|
@ -371,8 +371,8 @@ For each wrapped structure and class, a <tt>swig_ref</tt> will be exposed that h
|
|||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>octave:1> example;
|
||||
octave:2> p=example.Point();
|
||||
<pre>octave:1> swigexample;
|
||||
octave:2> p=swigexample.Point();
|
||||
octave:3> p.x=3;
|
||||
octave:4> p.y=5;
|
||||
octave:5> p.x, p.y
|
||||
|
|
@ -406,9 +406,9 @@ public:
|
|||
can be used from Octave like this
|
||||
</p>
|
||||
<div class="targetlang">
|
||||
<pre>octave:1> example;
|
||||
octave:2> p1=example.Point(3,5);
|
||||
octave:3> p2=example.Point(1,2);
|
||||
<pre>octave:1> swigexample;
|
||||
octave:2> p1=swigexample.Point(3,5);
|
||||
octave:3> p2=swigexample.Point(1,2);
|
||||
octave:4> p1.distance(p2)
|
||||
ans = 3.6056
|
||||
</pre></div>
|
||||
|
|
@ -649,7 +649,7 @@ C++ class and function templates are fully supported as in other modules, in tha
|
|||
For example, function templates can be instantiated as follows:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%inline {
|
||||
template<class __scalar>
|
||||
__scalar mul(__scalar a,__scalar b) {
|
||||
|
|
@ -677,7 +677,7 @@ ans = 22 + 46i
|
|||
Similarly, class templates can be instantiated as in the following example,
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%include <std_complex.i>
|
||||
%include <std_string.i>
|
||||
%inline {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue