"Fossies" - the Fresh Open Source Software Archive

Member "swig-4.0.0/Doc/Manual/Octave.html" (28 Apr 2019, 29730 Bytes) of package /linux/privat/swig-4.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
    2 <html>
    3 <head>
    4 <title>SWIG and Octave</title>
    5 <link rel="stylesheet" type="text/css" href="style.css">
    6 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    7 </head>
    8 
    9 
   10 <body bgcolor="#ffffff">
   11 
   12 <H1><a name="Octave">29 SWIG and Octave</a></H1>
   13 <!-- INDEX -->
   14 <div class="sectiontoc">
   15 <ul>
   16 <li><a href="#Octave_nn2">Preliminaries</a>
   17 <li><a href="#Octave_nn3">Running SWIG</a>
   18 <ul>
   19 <li><a href="#Octave_nn4">Command-line options</a>
   20 <li><a href="#Octave_nn5">Compiling a dynamic module</a>
   21 <li><a href="#Octave_nn6">Using your module</a>
   22 </ul>
   23 <li><a href="#Octave_nn7">A tour of basic C/C++ wrapping</a>
   24 <ul>
   25 <li><a href="#Octave_nn8">Modules</a>
   26 <li><a href="#Octave_nn9">Functions</a>
   27 <li><a href="#Octave_nn10">Global variables</a>
   28 <li><a href="#Octave_nn11">Constants and enums</a>
   29 <li><a href="#Octave_nn12">Pointers</a>
   30 <li><a href="#Octave_nn13">Structures and C++ classes</a>
   31 <li><a href="#Octave_nn15">C++ inheritance</a>
   32 <li><a href="#Octave_nn17">C++ overloaded functions</a>
   33 <li><a href="#Octave_nn18">C++ operators</a>
   34 <li><a href="#Octave_nn19">Class extension with %extend</a>
   35 <li><a href="#Octave_nn20">C++ templates</a>
   36 <li><a href="#Octave_nn21">C++ Smart Pointers</a>
   37 <ul>
   38 <li><a href="#Octave_smart_pointers_shared_ptr">The shared_ptr Smart Pointer</a>
   39 <li><a href="#Octave_smart_pointers_generic">Generic Smart Pointers</a>
   40 </ul>
   41 <li><a href="#Octave_nn22">Directors (calling Octave from C++ code)</a>
   42 <li><a href="#Octave_nn23">Threads</a>
   43 <li><a href="#Octave_nn24">Memory management</a>
   44 <li><a href="#Octave_nn25">STL support</a>
   45 <li><a href="#Octave_nn26">Matrix typemaps</a>
   46 </ul>
   47 </ul>
   48 </div>
   49 <!-- INDEX -->
   50 
   51 
   52 
   53 <p>
   54          Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB.
   55 More information can be found at <a href="http://www.gnu.org/software/octave/">Octave web site</a>. 
   56 </p>
   57 
   58 <p>
   59 This chapter is intended to give an introduction to using the module. You should also read the SWIG documentation that is not specific to Octave.
   60 Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
   61 </p>
   62 
   63 <H2><a name="Octave_nn2">29.1 Preliminaries</a></H2>
   64 
   65 
   66 <p>
   67 SWIG is regularly tested against the following versions of Octave: 3.8, 4.0, 4.2.
   68 </p>
   69 
   70 <p>
   71 Every effort is made to maintain backward compatibility with older versions of Octave.
   72 This cannot be guaranteed however, as in recent times new Octave releases have required nontrivial updates to SWIG, which may break backward compatibility for older Octave versions against which SWIG is not regularly tested.
   73 </p>
   74 
   75 <p>
   76 The SWIG runtime exports the function <tt>swig_octave_prereq()</tt> for checking the version of Octave.
   77 </p>
   78 
   79 <H2><a name="Octave_nn3">29.2 Running SWIG</a></H2>
   80 
   81 
   82 <p>
   83 Let's start with a very simple SWIG interface file, example.i:
   84 </p>
   85 
   86 <div class="code"><pre>
   87 %module swigexample
   88 %{
   89 #include "example.h"
   90 %}
   91 int gcd(int x, int y);
   92 extern double Foo; </pre></div>
   93 
   94 <p>
   95 To build an Octave module when wrapping C code, run SWIG using the <tt>-octave</tt> option:
   96 </p>
   97 
   98 <div class="shell"><pre>$ swig -octave -o example_wrap.cpp example.i </pre></div>
   99 
  100 <p>
  101 The <tt>-c++</tt> option is also required when wrapping C++ code:
  102 </p>
  103 
  104 
  105 <div class="shell"><pre>$ swig -octave -c++ -o example_wrap.cpp example.i </pre></div>
  106 
  107 <p>
  108 This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
  109 </p>
  110 
  111 <H3><a name="Octave_nn4">29.2.1 Command-line options</a></H3>
  112 
  113 
  114 <p>
  115 The swig command line has a number of options you can use, like to redirect its output. Use <tt>swig -help</tt> to learn about these.
  116 Options specific to the Octave module are:
  117 </p>
  118 
  119 <div class="shell">
  120 <pre>$ swig -octave -help
  121 ...
  122 Octave Options (available with -octave)
  123      -globals <em>name</em> - Set <em>name</em> used to access C global variables [default: 'cvar']
  124                      Use '.' to load C global variables into module namespace
  125      -opprefix <em>str</em> - Prefix <em>str</em> for global operator functions [default: 'op_']
  126 </pre></div>
  127 
  128 <p>
  129 The <em>-globals</em> option sets the name of the variable which is the namespace for C global variables exported by the module.
  130 The special name "." loads C global variables into the module namespace, i.e. alongside C functions and structs exported by the module.
  131 The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
  132 </p>
  133 
  134 <H3><a name="Octave_nn5">29.2.2 Compiling a dynamic module</a></H3>
  135 
  136 
  137 <p>
  138 Octave modules are DLLs/shared objects having the ".oct" suffix.
  139 Building an oct file is usually done with the mkoctfile command (either within Octave itself, or from the shell). For example,
  140 </p>
  141 
  142 <div class="shell"><pre>
  143 $ swig -octave -c++ -o example_wrap.cpp example.i
  144 $ mkoctfile example_wrap.cpp example.c
  145 </pre></div>
  146 
  147 <p>
  148         where "example.c" is the file containing the gcd() implementation. 
  149 </p>
  150 
  151 <p>
  152         mkoctfile can also be used to extract the build parameters required to invoke the compiler and linker yourself. See the Octave manual and mkoctfile man page. 
  153 </p>
  154 
  155 <p>
  156         mkoctfile will produce "swigexample.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking 
  157 </p>
  158 
  159           <div class="targetlang"><pre>octave:1&gt; swigexample</pre></div>
  160 
  161 <H3><a name="Octave_nn6">29.2.3 Using your module</a></H3>
  162 
  163 
  164 <p>
  165 Assuming all goes well, you will be able to do this: 
  166         <br>
  167 </p>
  168 
  169           <div class="targetlang"><pre>$ octave -q
  170 octave:1&gt; swigexample
  171 octave:2&gt; swigexample.gcd(4, 6)
  172 ans =  2
  173 octave:3&gt; swigexample.cvar.Foo
  174 ans =  3
  175 octave:4&gt; swigexample.cvar.Foo=4;
  176 octave:5&gt; swigexample.cvar.Foo
  177 ans =  4 </pre></div>
  178 
  179 <H2><a name="Octave_nn7">29.3 A tour of basic C/C++ wrapping</a></H2>
  180 
  181 
  182 <H3><a name="Octave_nn8">29.3.1 Modules</a></H3>
  183 
  184 
  185 <p>
  186 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.
  187 </p>
  188 
  189 <p>
  190 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".
  191 </p>
  192 
  193 <p>
  194 To load an Octave module, simply type its name:
  195 </p>
  196 
  197 <div class="targetlang"><pre>
  198 octave:1&gt; swigexample;
  199 octave:2&gt; gcd(4, 6)
  200 ans =  2
  201 octave:3&gt; cvar.Foo
  202 ans =  3
  203 octave:4&gt; cvar.Foo=4;
  204 octave:5&gt; cvar.Foo
  205 ans =  4
  206 </pre></div>
  207 
  208 <p>
  209 Modules can also be loaded from within functions, even before being loaded in the base context.
  210 If the module is also used in the base context, however, it must first be loaded again:
  211 </p>
  212 
  213 <div class="targetlang"><pre>
  214 octave:1&gt; function l = my_lcm(a, b)
  215 &gt; swigexample
  216 &gt; l = abs(a*b)/swigexample.gcd(a, b);
  217 &gt; endfunction
  218 octave:2&gt; my_lcm(4, 6)
  219 ans =  12
  220 octave:3&gt; swigexample.gcd(4, 6)
  221 error: can't perform indexing operations for &lt;unknown type&gt; type
  222 octave:3&gt; swigexample;
  223 octave:4&gt; swigexample.gcd(4, 6)
  224 ans =  2
  225 </pre></div>
  226 
  227 <H3><a name="Octave_nn9">29.3.2 Functions</a></H3>
  228 
  229 
  230 <p>
  231 Global functions are wrapped as new Octave built-in functions. For example, 
  232 </p>
  233 
  234       <div class="code"><pre>&#037;module swigexample
  235 int fact(int n); </pre></div>
  236 
  237 <p>
  238      creates a built-in function <tt>swigexample.fact(n)</tt> that works exactly like you think it does: 
  239 </p>
  240 
  241     <div class="targetlang"><pre>octave:1&gt; swigexample.fact(4)
  242 24 </pre></div>
  243 
  244 <H3><a name="Octave_nn10">29.3.3 Global variables</a></H3>
  245 
  246 
  247 <p>
  248      Global variables are a little special in Octave. Given a global variable: 
  249 </p>
  250 
  251 <div class="code"><pre>%module swigexample
  252 extern double Foo;
  253 </pre></div>
  254 
  255 <p>
  256     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. 
  257 </p>
  258 
  259     <div class="targetlang"><pre>octave:1&gt; swigexample;
  260 octave:2&gt; c=swigexample.cvar.Foo
  261 c =  3
  262 octave:3&gt; swigexample.cvar.Foo=4;
  263 octave:4&gt; c
  264 c =  3
  265 octave:5&gt; swigexample.cvar.Foo
  266 ans =  4</pre></div>
  267 
  268 <p>
  269 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: 
  270 </p>
  271 
  272     <div class="code"><pre>%module swigexample
  273 %immutable;
  274 extern double Foo;
  275 %mutable;
  276 </pre></div>
  277 
  278 <p>
  279      SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called. 
  280 </p>
  281 
  282     <div class="targetlang"><pre>octave:1&gt; swigexample
  283 octave:2&gt; swigexample.Foo=4
  284 error: attempt to set immutable member variable
  285 error: assignment failed, or no method for `swig_type = scalar'
  286 error: evaluating assignment expression near line 2, column 12 </pre></div>
  287 
  288 <p>
  289     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. 
  290 </p>
  291 
  292     <div class="targetlang"><pre>octave:1&gt; swigexample;
  293 octave:2&gt; swigexample.PI=3.142;
  294 octave:3&gt; swigexample.PI
  295 ans =  3.1420 </pre></div>
  296 
  297 <H3><a name="Octave_nn11">29.3.4 Constants and enums</a></H3>
  298 
  299 
  300 <p>
  301      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: 
  302 </p>
  303 
  304     <div class="code"><pre>%module swigexample
  305 %constant int ICONST=42;
  306 #define    SCONST      "Hello World"
  307 enum Days{SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY};
  308 </pre></div>
  309 
  310 <p>
  311     This is 'effectively' converted into the following Octave code: 
  312 </p>
  313 
  314     <div class="targetlang"><pre>swigexample.ICONST=42
  315 swigexample.SCONST="Hello World"
  316 swigexample.SUNDAY=0
  317 .... </pre></div>
  318 
  319 <H3><a name="Octave_nn12">29.3.5 Pointers</a></H3>
  320 
  321 
  322 <p>
  323       C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the &lt;file.h&gt; interface:
  324       C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the &lt;file.h&gt; interface:
  325 </p>
  326 
  327 <div class="code"><pre>%module swigexample
  328 FILE *fopen(const char *filename, const char *mode);
  329 int fputs(const char *, FILE *);
  330 int fclose(FILE *);
  331 </pre></div>
  332 
  333 <p>
  334 When wrapped, you will be able to use the functions in a natural way from Octave. For example:
  335 </p>
  336 
  337 <div class="targetlang"><pre>
  338 octave:1&gt; swigexample;
  339 octave:2&gt; f=swigexample.fopen("w", "junk");
  340 octave:3&gt; swigexample.fputs("Hello world", f);
  341 octave:4&gt; swigexample.fclose(f);
  342 </pre></div>
  343 
  344 <p>
  345      Simply printing the value of a wrapped C++ type will print its typename. E.g.,
  346 </p>
  347 
  348     <div class="targetlang"><pre>octave:1&gt; swigexample;
  349 octave:2&gt; f=swigexample.fopen("junk", "w");
  350 octave:3&gt; f
  351 f =
  352 
  353 {
  354   _p_FILE, ptr = 0x9b0cd00
  355 } </pre></div>
  356 
  357 <p>
  358     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).
  359 </p>
  360 
  361     <div class="targetlang"><pre>octave:1&gt; swigexample;
  362 octave:2&gt; f=swigexample.fopen("not there", "r");
  363 error: value on right hand side of assignment is undefined
  364 error: evaluating assignment expression near line 2, column 2 </pre></div>
  365 
  366 <H3><a name="Octave_nn13">29.3.6 Structures and C++ classes</a></H3>
  367 
  368 
  369 <p>
  370      SWIG wraps C structures and C++ classes by using a special Octave type called a <tt>swig_ref</tt>. A <tt>swig_ref</tt> contains a reference to one or more instances of C/C++ objects, or just the type information for an object.
  371 For each wrapped structure and class, a <tt>swig_ref</tt> will be exposed that has the name of the type. When invoked as a function, it creates a new object of its type and returns a <tt>swig_ref</tt> that points to that instance. This provides a very natural interface. For example, 
  372 </p>
  373 
  374     <div class="code"><pre>struct Point{
  375   int x, y;
  376 };
  377 </pre></div>
  378 
  379 <p>
  380     is used as follows: 
  381 </p>
  382 
  383     <div class="targetlang">
  384       <pre>octave:1&gt; swigexample;
  385 octave:2&gt; p=swigexample.Point();
  386 octave:3&gt; p.x=3;
  387 octave:4&gt; p.y=5;
  388 octave:5&gt; p.x, p.y
  389 ans =  3
  390 ans =  5 
  391 </pre></div>
  392 <p>
  393 In C++, invoking the type object in this way calls the object's constructor.
  394 <tt>swig_ref</tt> objects can also be acquired by having a wrapped function return a pointer, reference, or value of a non-primitive type. 
  395 </p>
  396 <p>
  397 The swig_ref type handles indexing operations such that usage maps closely to what you would have in C/C++. 
  398 Structure members are accessed as in the above example, by calling set and get methods for C++ variables. 
  399 
  400 Methods also work as expected. For example, code wrapped in the following way
  401 </p>
  402 
  403     <div class="code"><pre>class Point{
  404 public:
  405   int x, y;
  406   Point(int _x, int _y) : x(_x), y(_y) {}
  407   double distance(const Point&amp; rhs) {
  408     return sqrt(pow(x-rhs.x, 2)+pow(y-rhs.y, 2));
  409   }
  410   void set(int _x, int _y) {
  411     x=_x; y=_y;
  412   }
  413 };
  414 </pre></div>
  415 <p>
  416 can be used from Octave like this
  417 </p>
  418     <div class="targetlang">
  419       <pre>octave:1&gt; swigexample;
  420 octave:2&gt; p1=swigexample.Point(3, 5);
  421 octave:3&gt; p2=swigexample.Point(1, 2);
  422 octave:4&gt; p1.distance(p2)
  423 ans =  3.6056
  424 </pre></div>
  425 <p>
  426 By using the <tt>swig_this()</tt> and <tt>swig_type()</tt> functions, one can discover the pointers to and types of the underlying C/C++ object.
  427 </p>
  428 
  429     <div class="targetlang">
  430       <pre>
  431 octave:5> swig_this(p1)
  432 ans = 162504808
  433 octave:6> swig_type(p1)
  434 ans = Point
  435 </pre></div>
  436 <p>
  437 Note that <tt>swig_ref</tt> is a reference-counted pointer to a C/C++ object/type, and as such has pass-by-reference semantics. For example if one has a allocated a single object but has two <tt>swig_ref</tt>'s pointing to it, modifying the object through either of them will change the single allocated object.
  438 This differs from the usual pass-by-value (copy-on-write) semantics that Octave maintains for built-in types. For example, in the following snippet, modifying <tt>b</tt> does not modify <tt>a</tt>,
  439 </p>
  440 
  441     <div class="targetlang">
  442       <pre>
  443 octave:7> a=struct('x', 4)
  444 a =
  445 {
  446   x =  4
  447 }
  448 
  449 octave:8> b=a
  450 b =
  451 {
  452   x =  4
  453 }
  454 
  455 octave:9> b.y=4
  456 b =
  457 {
  458   x =  4
  459   y =  4
  460 }
  461 
  462 octave:10> a
  463 a =
  464 {
  465   x =  4
  466 }
  467 </pre></div>
  468 <p>
  469 However, when dealing with wrapped objects, one gets the behavior
  470 </p>
  471 
  472     <div class="targetlang">
  473       <pre>
  474 octave:2> a=Point(3, 5)
  475 a =
  476 
  477 {
  478   Point, ptr = 0x9afbbb0
  479 }
  480 
  481 octave:3> b=a
  482 b =
  483 
  484 {
  485   Point, ptr = 0x9afbbb0
  486 }
  487 
  488 octave:4> b.set(2, 1);
  489 octave:5> b.x, b.y
  490 ans =  2
  491 ans =  1
  492 octave:6> a.x, a.y
  493 ans =  2
  494 ans =  1
  495 </pre></div>
  496 
  497 <p>
  498 Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
  499 </p>
  500 
  501 <H3><a name="Octave_nn15">29.3.7 C++ inheritance</a></H3>
  502 
  503 
  504 <p>
  505 Single and multiple inheritance are fully supported. The <tt>swig_ref</tt> type carries type information along with any C++ object pointer it holds.
  506 This information contains the full class hierarchy. When an indexing operation (such as a method invocation) occurs, 
  507 the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
  508 </p>
  509 
  510 <H3><a name="Octave_nn17">29.3.8 C++ overloaded functions</a></H3>
  511 
  512 
  513 <p>
  514 Overloaded functions are supported, and handled as in other modules. That is, 
  515 each overload is wrapped separately (under internal names), and a dispatch function is also emitted under the external/visible name.
  516 The dispatch function selects which overload to call (if any) based on the passed arguments.
  517 <tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
  518 </p>
  519 
  520 <H3><a name="Octave_nn18">29.3.9 C++ operators</a></H3>
  521 
  522 
  523 <p>
  524 C++ operator overloading is supported, in a way similar to other modules.
  525 The <tt>swig_ref</tt> type supports all unary and binary operators between itself and all other types that exist in the system at module load time. When an operator is used (where one of the operands is a <tt>swig_ref</tt>), the runtime routes the call to either a member function of the given object, or to a global function whose named is derived from the types of the operands (either both or just the lhs or rhs).
  526 </p>
  527 <p>
  528 For example, if <tt>a</tt> and <tt>b</tt> are SWIG variables in Octave, <tt>a+b</tt> becomes <tt>a.__add__(b)</tt>. The wrapper is then free to implement __add__ to do whatever it wants. A wrapper may define the <tt>__add__</tt> function manually, %rename some other function to it, or %rename a C++ operator to it.
  529 </p>
  530 <p>
  531 By default the C++ operators are renamed to their corresponding Octave operators. So without doing any work, the following interface
  532 </p>
  533 <div class="code"><pre>
  534 %inline {
  535 struct A {
  536   int value;
  537   A(int _value) : value(_value) {}
  538   A operator+ (const A&amp; x) {
  539     return A(value+x.value);
  540   }
  541 };
  542 }
  543 </pre></div>
  544 <p>
  545 is usable from Octave like this:
  546 </p>
  547 <div class="targetlang"><pre>
  548 a=A(2), b=A(3), c=a+b
  549 assert(c.value==5);
  550 </pre></div>
  551 <p>
  552 Octave operators are mapped in the following way:
  553 </p>
  554 <div class="code"><pre>
  555 __brace__      a{args}
  556 __brace_asgn__ a{args} = rhs
  557 __paren__      a(args)
  558 __paren_asgn__ a(args) = rhs
  559 __str__        generates string rep
  560 __not__        !a
  561 __uplus__      +a
  562 __uminus__     -a
  563 __transpose__  a.'
  564 __hermitian__  a'
  565 __incr__       a++
  566 __decr__       a--
  567 __add__        a + b
  568 __sub__        a - b
  569 __mul__        a * b
  570 __div__        a / b
  571 __pow__        a ^ b
  572 __ldiv__       a \ b
  573 __lshift__     a << b
  574 __rshift__     a >> b
  575 __lt__         a < b
  576 __le__         a <= b
  577 __eq__         a == b
  578 __ge__         a >= b
  579 __gt__         a > b
  580 __ne__         a != b
  581 __el_mul__     a .* b
  582 __el_div__     a ./ b
  583 __el_pow__     a .^ b
  584 __el_ldiv__    a .\ b
  585 __el_and__     a &amp; b
  586 __el_or__      a | b
  587 </pre></div>
  588 <p>
  589 On the C++ side, the default mappings are as follows:
  590 </p>
  591 <div class="code"><pre>
  592 %rename(__add__)       *::operator+;
  593 %rename(__add__)       *::operator+();
  594 %rename(__add__)       *::operator+() const;
  595 %rename(__sub__)       *::operator-;
  596 %rename(__uminus__)    *::operator-();
  597 %rename(__uminus__)    *::operator-() const;
  598 %rename(__mul__)       *::operator*;
  599 %rename(__div__)       *::operator/;
  600 %rename(__mod__)       *::operator%;
  601 %rename(__lshift__)    *::operator<<;
  602 %rename(__rshift__)    *::operator>>;
  603 %rename(__el_and__)    *::operator&amp;&amp;;
  604 %rename(__el_or__)     *::operator||;
  605 %rename(__xor__)       *::operator^;
  606 %rename(__invert__)    *::operator~;
  607 %rename(__lt__)        *::operator<;
  608 %rename(__le__)        *::operator<=;
  609 %rename(__gt__)        *::operator>;
  610 %rename(__ge__)        *::operator>=;
  611 %rename(__eq__)        *::operator==;
  612 %rename(__ne__)        *::operator!=;
  613 %rename(__not__)       *::operator!;
  614 %rename(__incr__)      *::operator++;
  615 %rename(__decr__)      *::operator--;
  616 %rename(__paren__)     *::operator();
  617 %rename(__brace__)     *::operator[];
  618 </pre></div>
  619 
  620 <p>
  621 Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory.
  622 </p>
  623 
  624 <H3><a name="Octave_nn19">29.3.10 Class extension with %extend</a></H3>
  625 
  626 
  627 <p>
  628 The %extend directive works the same as in other modules.
  629 </p>
  630 <p>
  631 You can use it to define special behavior, like for example defining Octave operators not mapped to C++ operators, or defining certain Octave mechanisms such as how an object prints. For example, the <tt>octave_value::{is_string, string_value, print}</tt> functions are routed to a special method <tt>__str__</tt> that can be defined inside an %extend.
  632 </p>
  633 <div class="code"><pre>
  634 %extend A {
  635 string __str__() {
  636   stringstream sout;
  637   sout&lt;&lt;$self->value;
  638   return sout.str();
  639 }
  640 }
  641 </pre></div>
  642 <p>
  643 Then in Octave one gets,
  644 </p>
  645 <div class="targetlang"><pre>
  646 octave:1&gt; a=A(4);
  647 octave:2&gt; a
  648 a = 4
  649 octave:3&gt; printf("%s\n", a);
  650 4
  651 octave:4&gt; a.__str__()
  652 4
  653 </pre></div>
  654 
  655 <p>
  656 Similarly, Octave can use the <tt>__float__</tt> method to convert an object to a numeric value.
  657 </p>
  658 
  659 <p>
  660 Octave 3.8.0 and later versions will also map unary functions X() to the corresponding <tt>__X__</tt> method, where X includes: abs(), acos(), acosh(), angle(), arg(), asin(), asinh(), atan(), atanh(), cbrt(), ceil(), conj(), cos(), cosh(), dawson(), erf(), erfc(), erfcinv(), erfcx(), erfi(), erfinv(), exp(), expm1(), finite(), fix(), floor(), gamma(), imag(), isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), isinf(), islower(), isna(), isnan(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), lgamma(), log(), log10(), log1p(), log2(), real(), round(), roundb(), signbit(), signum(), sin(), sinh(), sqrt(), tan(), tanh(), toascii(), tolower(), toupper()
  661 </p>
  662 
  663 <H3><a name="Octave_nn20">29.3.11 C++ templates</a></H3>
  664 
  665 
  666 <p>
  667 C++ class and function templates are fully supported as in other modules, in that the %template directive may used to create explicit instantiations of templated types.
  668 For example, function templates can be instantiated as follows:
  669 </p>
  670 
  671 <div class="code"><pre>%module swigexample
  672 %inline {
  673   template&lt;class __scalar&gt;
  674     __scalar mul(__scalar a, __scalar b) {
  675     return a*b;
  676   }
  677 }
  678 %include &lt;std_complex.i&gt;
  679 %template(mul) mul&lt;std::complex&lt;double&gt; &gt;
  680 %template(mul) mul&lt;double&gt;
  681 </pre></div>
  682 <p>
  683 and then used from Octave
  684 </p>
  685 
  686 <div class="targetlang"><pre>
  687 octave:1> mul(4, 3)
  688 ans =  12
  689 octave:2> mul(4.2, 3.6)
  690 ans =  15.120
  691 octave:3> mul(3+4i, 10+2i)
  692 ans =  22 + 46i
  693 </pre></div>
  694 
  695 <p>
  696 Similarly, class templates can be instantiated as in the following example,
  697 </p>
  698 
  699 <div class="code"><pre>%module swigexample
  700 %include &lt;std_complex.i&gt;
  701 %include &lt;std_string.i&gt;
  702 %inline {
  703   #include &lt;sstream&gt;
  704   template&lt;class __scalar&gt; class sum {
  705     __scalar s;
  706   public:
  707     sum(__scalar _s=0) : s(_s) {}
  708     sum&amp; add(__scalar _s) {
  709       s+=_s;
  710       return *this;
  711     }
  712     std::string __str__() const {
  713       std::stringstream sout;
  714       sout&lt;&lt;s;
  715       return sout.str();
  716     }
  717   };
  718 }
  719 %template(sum_complex) sum&lt;std::complex&lt;double&gt; &gt;;
  720 %template(sum_double) sum&lt;double&gt;;
  721 </pre></div>
  722 
  723 <p>
  724 and then used from Octave
  725 </p>
  726 
  727 <div class="targetlang"><pre>
  728 octave:2> a=sum_complex(2+3i);
  729 octave:3> a.add(2)
  730 ans =
  731 
  732 (4, 3)
  733 octave:4> a.add(3+i)
  734 ans =
  735 
  736 (7, 4)
  737 </pre></div>
  738 
  739 
  740 <H3><a name="Octave_nn21">29.3.12 C++ Smart Pointers</a></H3>
  741 
  742 
  743 <H4><a name="Octave_smart_pointers_shared_ptr">29.3.12.1 The shared_ptr Smart Pointer</a></H4>
  744 
  745 
  746 <p>
  747 The C++11 standard provides <tt>std::shared_ptr</tt> which was derived from the Boost
  748 implementation, <tt>boost::shared_ptr</tt>.
  749 Both of these are available for Octave in the SWIG library and usage is outlined
  750 in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> library section.
  751 </p>
  752 
  753 
  754 <H4><a name="Octave_smart_pointers_generic">29.3.12.2 Generic Smart Pointers</a></H4>
  755 
  756 
  757 <p>
  758 C++ smart pointers are fully supported as in other modules.
  759 </p>
  760 
  761 <H3><a name="Octave_nn22">29.3.13 Directors (calling Octave from C++ code)</a></H3>
  762 
  763 
  764 <p>
  765 There is full support for SWIG Directors, which permits Octave code to subclass C++ classes, and implement their virtual methods.
  766 </p>
  767 <p>
  768 Octave has no direct support for object oriented programming, however the <tt>swig_ref</tt> type provides some of this support. You can manufacture a <tt>swig_ref</tt> using the <tt>subclass</tt> function (provided by the SWIG/Octave runtime).
  769 </p>
  770 <p>
  771 For example,
  772 </p>
  773 <div class="targetlang"><pre>
  774 octave:1&gt; a=subclass();
  775 octave:2&gt; a.my_var = 4;
  776 octave:3&gt; a.my_method = @(self) printf("my_var = ", self.my_var);
  777 octave:4&gt; a.my_method();
  778 my_var = 4
  779 </pre></div>
  780 <p>
  781 <tt>subclass()</tt> can also be used to subclass one or more C++ types. Suppose you have an interface defined by
  782 </p>
  783 <div class="code"><pre>
  784 %inline {
  785 class A {
  786 public:
  787   virtual my_method() {
  788     printf("c-side routine called\n");
  789   }
  790 };
  791 void call_your_method(A&amp; a) {
  792   a.my_method();
  793 }
  794 }
  795 </pre></div>
  796 <p>
  797 Then from Octave you can say:
  798 </p>
  799 <div class="targetlang"><pre>
  800 octave:1&gt; B=@() subclass(A(), @my_method);
  801 octave:2&gt; function my_method(self)
  802 octave:3&gt;   printf("octave-side routine called\n");
  803 octave:4&gt; end
  804 octave:5&gt; call_your_method(B());
  805 octave-side routine called
  806 </pre></div>
  807 <p>
  808 or more concisely,
  809 </p>
  810 <div class="targetlang"><pre>
  811 octave:1&gt; B=@() subclass(A(), 'my_method', @(self) printf("octave-side routine called\n"));
  812 octave:2&gt; call_your_method(B());
  813 octave-side routine called
  814 </pre></div>
  815 <p>
  816 Note that you have to enable directors via the %feature directive (see other modules for this).
  817 </p>
  818 <p>
  819 <tt>subclass()</tt> will accept any number of C++ bases or other <tt>subclass()</tt>'ed objects, <tt>(string, octave_value)</tt> pairs, and <tt>function_handles</tt>. In the first case, these are taken as base classes; in the second case, as named members (either variables or functions, depending on whether the given value is a function handle); in the third case, as member functions whose name is taken from the given function handle. E.g.,
  820 </p>
  821 <div class="targetlang"><pre>
  822 octave:1&gt; B=@(some_var=2) subclass(A(), 'some_var', some_var, @some_func, 'another_func',
  823 @(self) do_stuff())
  824 </pre></div>
  825 <p>
  826 You can also assign non-C++ member variables and functions after construct time. There is no support for non-C++ static members.
  827 </p>
  828 <p>
  829 There is limited support for explicitly referencing C++ bases. So, in the example above, we could have
  830 </p>
  831 <div class="targetlang"><pre>
  832 octave:1&gt; B=@() subclass(A(), @my_method);
  833 octave:2&gt; function my_method(self)
  834 octave:3&gt;   self.A.my_method();
  835 octave:4&gt;   printf("octave-side routine called\n");
  836 octave:5&gt; end
  837 octave:6&gt; call_your_method(B());
  838 c-side routine called
  839 octave-side routine called
  840 </pre></div>
  841 
  842 <H3><a name="Octave_nn23">29.3.14 Threads</a></H3>
  843 
  844 
  845 <p>
  846 The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
  847 </p>
  848 
  849 <H3><a name="Octave_nn24">29.3.15 Memory management</a></H3>
  850 
  851 
  852 <p>
  853 As noted above, <tt>swig_ref</tt> represents a reference counted pointer to a C/C++-side object. It also contains a flag indicating whether Octave or the C/C++ code owns the object. If Octave owns it, any destructors will be called when the reference count reaches zero. If the C/C++ side owns the object, then destructors will not be called when the reference count goes to zero.
  854 </p>
  855 <p>
  856 For example,
  857 <div class="code"><pre>
  858 %inline {
  859 class A {
  860 public:
  861   A() { printf("A constructing\n"); }
  862   ~A() { printf("A destructing\n"); }
  863 };
  864 }
  865 </pre></div>
  866 <p>
  867 Would produce this behavior in Octave:
  868 </p>
  869 <div class="targetlang"><pre>
  870 octave:1&gt; a=A();
  871 A constructing
  872 octave:2&gt; b=a;
  873 octave:3&gt; clear a;
  874 octave:4&gt; b=4;
  875 A destructing
  876 </pre></div>
  877 <p>
  878 The %newobject directive may be used to control this behavior for pointers returned from functions.
  879 <p>
  880 In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
  881 </p>
  882 
  883 <H3><a name="Octave_nn25">29.3.16 STL support</a></H3>
  884 
  885 
  886 <p>
  887 Various STL library files are provided for wrapping STL containers.
  888 </p>
  889 
  890 <H3><a name="Octave_nn26">29.3.17 Matrix typemaps</a></H3>
  891 
  892 
  893 <p>
  894 Octave provides a rich set of classes for dealing with matrices. Currently there are no built-in typemaps to deal with those. However, these are relatively straight forward for users to add themselves (see the docs on typemaps). Without much work (a single typemap decl-- say, 5 lines of code in the interface file), it would be possible to have a function
  895 </p>
  896 <div class="code"><pre>
  897 double my_det(const double* mat, int m, int n);
  898 </pre></div>
  899 <p>
  900 that is accessed from Octave as,
  901 </p>
  902 <div class="targetlang"><pre>
  903 octave:1&gt; my_det(rand(4));
  904 ans = -0.18388
  905 </pre></div>
  906 
  907     <tt><br></tt>
  908   </body>
  909 </html>