1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Octave</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#ffffff">
<H1><a name="Octave"></a>30 SWIG and Octave</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Octave_nn2">Preliminaries</a>
<li><a href="#Octave_nn3">Running SWIG</a>
<ul>
<li><a href="#Octave_nn4">Command-line options</a>
<li><a href="#Octave_nn5">Compiling a dynamic module</a>
<li><a href="#Octave_nn6">Using your module</a>
</ul>
<li><a href="#Octave_nn7">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="#Octave_nn8">Modules</a>
<li><a href="#Octave_nn9">Functions</a>
<li><a href="#Octave_nn10">Global variables</a>
<li><a href="#Octave_nn11">Constants and enums</a>
<li><a href="#Octave_nn12">Pointers</a>
<li><a href="#Octave_nn13">Structures and C++ classes</a>
<li><a href="#Octave_nn15">C++ inheritance</a>
<li><a href="#Octave_nn17">C++ overloaded functions</a>
<li><a href="#Octave_nn18">C++ operators</a>
<li><a href="#Octave_nn19">Class extension with %extend</a>
<li><a href="#Octave_nn20">C++ templates</a>
<li><a href="#Octave_nn21">C++ Smart Pointers</a>
<li><a href="#Octave_nn22">Directors (calling Octave from C++ code)</a>
<li><a href="#Octave_nn23">Threads</a>
<li><a href="#Octave_nn24">Memory management</a>
<li><a href="#Octave_nn25">STL support</a>
<li><a href="#Octave_nn26">Matrix typemaps</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB.
More information can be found at <a href="http://www.gnu.org/software/octave/">Octave web site</a>.
</p>
<p>
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.
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).
</p>
<H2><a name="Octave_nn2"></a>30.1 Preliminaries</H2>
<p>
As of SWIG 3.0.0, the Octave module has been tested with Octave versions 3.0.5, 3.2.4, 3.4.3, 3.6.4, and 3.8.0.
Use of Octave versions older than 3.x.x is not recommended, as these versions are no longer tested with SWIG.
</p>
<H2><a name="Octave_nn3"></a>30.2 Running SWIG</H2>
<p>
Let's start with a very simple SWIG interface file, example.i:
</p>
<div class="code"><pre>
%module swigexample
%{
#include "example.h"
%}
int gcd(int x, int y);
extern double Foo; </pre></div>
<p>
To build an Octave module when wrapping C code, run SWIG using the <tt>-octave</tt> option:
</p>
<div class="shell"><pre>$ swig -octave -o example_wrap.cpp example.i </pre></div>
<p>
The <tt>-c++</tt> option is also required when wrapping C++ code:
</p>
<div class="shell"><pre>$ swig -octave -c++ -o example_wrap.cpp example.i </pre></div>
<p>
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.
</p>
<H3><a name="Octave_nn4"></a>30.2.1 Command-line options</H3>
<p>
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.
Options specific to the Octave module are:
</p>
<div class="shell">
<pre>$ swig -octave -help
...
Octave Options (available with -octave)
-globals <em>name</em> - Set <em>name</em> used to access C global variables [default: 'cvar']
Use '.' to load C global variables into module namespace
-opprefix <em>str</em> - Prefix <em>str</em> for global operator functions [default: 'op_']
</pre></div>
<p>
The <em>-globals</em> option sets the name of the variable which is the namespace for C global variables exported by the module.
The special name "." loads C global variables into the module namespace, i.e. alongside C functions and structs exported by the module.
The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
</p>
<H3><a name="Octave_nn5"></a>30.2.2 Compiling a dynamic module</H3>
<p>
Octave modules are DLLs/shared objects having the ".oct" suffix.
Building an oct file is usually done with the mkoctfile command (either within Octave itself, or from the shell). For example,
</p>
<div class="shell"><pre>
$ swig -octave -c++ -o example_wrap.cpp example.i
$ mkoctfile example_wrap.cpp example.c
</pre></div>
<p>
where "example.c" is the file containing the gcd() implementation.
</p>
<p>
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.
</p>
<p>
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> swigexample</pre></div>
<H3><a name="Octave_nn6"></a>30.2.3 Using your module</H3>
<p>
Assuming all goes well, you will be able to do this:
<br>
</p>
<div class="targetlang"><pre>$ octave -q
octave:1> swigexample
octave:2> swigexample.gcd(4,6)
ans = 2
octave:3> swigexample.cvar.Foo
ans = 3
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>
<H3><a name="Octave_nn8"></a>30.3.1 Modules</H3>
<p>
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>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>
To load an Octave module, simply type its name:
</p>
<div class="targetlang"><pre>
octave:1> swigexample;
octave:2> gcd(4,6)
ans = 2
octave:3> cvar.Foo
ans = 3
octave:4> cvar.Foo=4;
octave:5> cvar.Foo
ans = 4
</pre></div>
<p>
Modules can also be loaded from within functions, even before being loaded in the base context.
If the module is also used in the base context, however, it must first be loaded again:
</p>
<div class="targetlang"><pre>
octave:1> function l = my_lcm(a,b)
> swigexample
> l = abs(a*b)/swigexample.gcd(a,b);
> endfunction
octave:2> my_lcm(4,6)
ans = 12
octave:3> swigexample.gcd(4,6)
error: can't perform indexing operations for <unknown type> type
octave:3> swigexample;
octave:4> swigexample.gcd(4,6)
ans = 2
</pre></div>
<H3><a name="Octave_nn9"></a>30.3.2 Functions</H3>
<p>
Global functions are wrapped as new Octave built-in functions. For example,
</p>
<div class="code"><pre>%module swigexample
int fact(int n); </pre></div>
<p>
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> swigexample.fact(4)
24 </pre></div>
<H3><a name="Octave_nn10"></a>30.3.3 Global variables</H3>
<p>
Global variables are a little special in Octave. Given a global variable:
</p>
<div class="code"><pre>%module swigexample
extern double Foo;
</pre></div>
<p>
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> swigexample;
octave:2> c=swigexample.cvar.Foo
c = 3
octave:3> swigexample.cvar.Foo=4;
octave:4> c
c = 3
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 swigexample
%immutable;
extern double Foo;
%mutable;
</pre></div>
<p>
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> 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>
<p>
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> 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>
<p>
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 swigexample
%constant int ICONST=42;
#define SCONST "Hello World"
enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
</pre></div>
<p>
This is 'effectively' converted into the following Octave code:
</p>
<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>
<p>
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:
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 swigexample
FILE *fopen(const char *filename, const char *mode);
int fputs(const char *, FILE *);
int fclose(FILE *);
</pre></div>
<p>
When wrapped, you will be able to use the functions in a natural way from Octave. For example:
</p>
<div class="targetlang"><pre>
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 its typename. E.g.,
</p>
<div class="targetlang"><pre>octave:1> swigexample;
octave:2> f=swigexample.fopen("junk","w");
octave:3> f
f =
{
_p_FILE, ptr = 0x9b0cd00
} </pre></div>
<p>
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> 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>
<H3><a name="Octave_nn13"></a>30.3.6 Structures and C++ classes</H3>
<p>
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.
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,
</p>
<div class="code"><pre>struct Point{
int x,y;
};
</pre></div>
<p>
is used as follows:
</p>
<div class="targetlang">
<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
ans = 3
ans = 5
</pre></div>
<p>
In C++, invoking the type object in this way calls the object's constructor.
<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.
</p>
<p>
The swig_ref type handles indexing operations such that usage maps closely to what you would have in C/C++.
Structure members are accessed as in the above example, by calling set and get methods for C++ variables.
Methods also work as expected. For example, code wrapped in the following way
</p>
<div class="code"><pre>class Point{
public:
int x,y;
Point(int _x,int _y) : x(_x),y(_y) {}
double distance(const Point& rhs) {
return sqrt(pow(x-rhs.x,2)+pow(y-rhs.y,2));
}
void set(int _x,int _y) {
x=_x; y=_y;
}
};
</pre></div>
<p>
can be used from Octave like this
</p>
<div class="targetlang">
<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>
<p>
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.
</p>
<div class="targetlang">
<pre>
octave:5> swig_this(p1)
ans = 162504808
octave:6> swig_type(p1)
ans = Point
</pre></div>
<p>
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.
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>,
</p>
<div class="targetlang">
<pre>
octave:7> a=struct('x',4)
a =
{
x = 4
}
octave:8> b=a
b =
{
x = 4
}
octave:9> b.y=4
b =
{
x = 4
y = 4
}
octave:10> a
a =
{
x = 4
}
</pre></div>
<p>
However, when dealing with wrapped objects, one gets the behavior
</p>
<div class="targetlang">
<pre>
octave:2> a=Point(3,5)
a =
{
Point, ptr = 0x9afbbb0
}
octave:3> b=a
b =
{
Point, ptr = 0x9afbbb0
}
octave:4> b.set(2,1);
octave:5> b.x, b.y
ans = 2
ans = 1
octave:6> a.x, a.y
ans = 2
ans = 1
</pre></div>
<p>
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.
</p>
<H3><a name="Octave_nn15"></a>30.3.7 C++ inheritance</H3>
<p>
Single and multiple inheritance are fully supported. The <tt>swig_ref</tt> type carries type information along with any C++ object pointer it holds.
This information contains the full class hierarchy. When an indexing operation (such as a method invocation) occurs,
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>.
</p>
<H3><a name="Octave_nn17"></a>30.3.8 C++ overloaded functions</H3>
<p>
Overloaded functions are supported, and handled as in other modules. That is,
each overload is wrapped separately (under internal names), and a dispatch function is also emitted under the external/visible name.
The dispatch function selects which overload to call (if any) based on the passed arguments.
<tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
</p>
<H3><a name="Octave_nn18"></a>30.3.9 C++ operators</H3>
<p>
C++ operator overloading is supported, in a way similar to other modules.
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).
</p>
<p>
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.
</p>
<p>
By default the C++ operators are renamed to their corresponding Octave operators. So without doing any work, the following interface
</p>
<div class="code"><pre>
%inline {
struct A {
int value;
A(int _value) : value(_value) {}
A operator+ (const A& x) {
return A(value+x.value);
}
};
}
</pre></div>
<p>
is usable from Octave like this:
</p>
<div class="targetlang"><pre>
a=A(2), b=A(3), c=a+b
assert(c.value==5);
</pre></div>
<p>
Octave operators are mapped in the following way:
</p>
<div class="code"><pre>
__brace a{args}
__brace_asgn a{args} = rhs
__paren a(args)
__paren_asgn a(args) = rhs
__str generates string rep
__not !a
__uplus +a
__uminus -a
__transpose a.'
__hermitian a'
__incr a++
__decr a--
__add a + b
__sub a - b
__mul a * b
__div a / b
__pow a ^ b
__ldiv a \ b
__lshift a << b
__rshift a >> b
__lt a < b
__le a <= b
__eq a == b
__ge a >= b
__gt a > b
__ne a != b
__el_mul a .* b
__el_div a ./ b
__el_pow a .^ b
__el_ldiv a .\ b
__el_and a & b
__el_or a | b
</pre></div>
<p>
On the C++ side, the default mappings are as follows:
</p>
<div class="code"><pre>
%rename(__add) *::operator+;
%rename(__add) *::operator+();
%rename(__add) *::operator+() const;
%rename(__sub) *::operator-;
%rename(__uminus) *::operator-();
%rename(__uminus) *::operator-() const;
%rename(__mul) *::operator*;
%rename(__div) *::operator/;
%rename(__mod) *::operator%;
%rename(__lshift) *::operator<<;
%rename(__rshift) *::operator>>;
%rename(__el_and) *::operator&&;
%rename(__el_or) *::operator||;
%rename(__xor) *::operator^;
%rename(__invert) *::operator~;
%rename(__lt) *::operator<;
%rename(__le) *::operator<=;
%rename(__gt) *::operator>;
%rename(__ge) *::operator>=;
%rename(__eq) *::operator==;
%rename(__ne) *::operator!=;
%rename(__not) *::operator!;
%rename(__incr) *::operator++;
%rename(__decr) *::operator--;
%rename(__paren) *::operator();
%rename(__brace) *::operator[];
</pre></div>
<p>
Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory.
</p>
<H3><a name="Octave_nn19"></a>30.3.10 Class extension with %extend</H3>
<p>
The %extend directive works the same as in other modules.
</p>
<p>
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.
</p>
<div class="code"><pre>
%extend A {
string __str() {
stringstream sout;
sout<<$self->value;
return sout.str();
}
}
</pre></div>
<p>
Then in Octave one gets,
</p>
<div class="targetlang"><pre>
octave:1> a=A(4);
octave:2> a
a = 4
octave:3> printf("%s\n",a);
4
octave:4> a.__str()
4
</pre></div>
<H3><a name="Octave_nn20"></a>30.3.11 C++ templates</H3>
<p>
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.
For example, function templates can be instantiated as follows:
</p>
<div class="code"><pre>%module swigexample
%inline {
template<class __scalar>
__scalar mul(__scalar a,__scalar b) {
return a*b;
}
}
%include <std_complex.i>
%template(mul) mul<std::complex<double> >
%template(mul) mul<double>
</pre></div>
<p>
and then used from Octave
</p>
<div class="targetlang"><pre>
octave:1> mul(4,3)
ans = 12
octave:2> mul(4.2,3.6)
ans = 15.120
octave:3> mul(3+4i,10+2i)
ans = 22 + 46i
</pre></div>
<p>
Similarly, class templates can be instantiated as in the following example,
</p>
<div class="code"><pre>%module swigexample
%include <std_complex.i>
%include <std_string.i>
%inline {
#include <sstream>
template<class __scalar> class sum {
__scalar s;
public:
sum(__scalar _s=0) : s(_s) {}
sum& add(__scalar _s) {
s+=_s;
return *this;
}
std::string __str() const {
std::stringstream sout;
sout<<s;
return sout.str();
}
};
}
%template(sum_complex) sum<std::complex<double> >;
%template(sum_double) sum<double>;
</pre></div>
<p>
and then used from Octave
</p>
<div class="targetlang"><pre>
octave:2> a=sum_complex(2+3i);
octave:3> a.add(2)
ans =
(4,3)
octave:4> a.add(3+i)
ans =
(7,4)
</pre></div>
<H3><a name="Octave_nn21"></a>30.3.12 C++ Smart Pointers</H3>
<p>
C++ smart pointers are fully supported as in other modules.
</p>
<H3><a name="Octave_nn22"></a>30.3.13 Directors (calling Octave from C++ code)</H3>
<p>
There is full support for SWIG Directors, which permits Octave code to subclass C++ classes, and implement their virtual methods.
</p>
<p>
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).
</p>
<p>
For example,
</p>
<div class="targetlang"><pre>
octave:1> a=subclass();
octave:2> a.my_var = 4;
octave:3> a.my_method = @(self) printf("my_var = ",self.my_var);
octave:4> a.my_method();
my_var = 4
</pre></div>
<p>
<tt>subclass()</tt> can also be used to subclass one or more C++ types. Suppose you have an interface defined by
</p>
<div class="code"><pre>
%inline {
class A {
public:
virtual my_method() {
printf("c-side routine called\n");
}
};
void call_your_method(A& a) {
a.my_method();
}
}
</pre></div>
<p>
Then from Octave you can say:
</p>
<div class="targetlang"><pre>
octave:1> B=@() subclass(A(),@my_method);
octave:2> function my_method(self)
octave:3> printf("octave-side routine called\n");
octave:4> end
octave:5> call_your_method(B());
octave-side routine called
</pre></div>
<p>
or more concisely,
</p>
<div class="targetlang"><pre>
octave:1> B=@() subclass(A(),'my_method',@(self) printf("octave-side routine called\n"));
octave:2> call_your_method(B());
octave-side routine called
</pre></div>
<p>
Note that you have to enable directors via the %feature directive (see other modules for this).
</p>
<p>
<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.,
</p>
<div class="targetlang"><pre>
octave:1> B=@(some_var=2) subclass(A(),'some_var',some_var,@some_func,'another_func',
@(self) do_stuff())
</pre></div>
<p>
You can also assign non-C++ member variables and functions after construct time. There is no support for non-C++ static members.
</p>
<p>
There is limited support for explicitly referencing C++ bases. So, in the example above, we could have
</p>
<div class="targetlang"><pre>
octave:1> B=@() subclass(A(),@my_method);
octave:2> function my_method(self)
octave:3> self.A.my_method();
octave:4> printf("octave-side routine called\n");
octave:5> end
octave:6> call_your_method(B());
c-side routine called
octave-side routine called
</pre></div>
<H3><a name="Octave_nn23"></a>30.3.14 Threads</H3>
<p>
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.
</p>
<H3><a name="Octave_nn24"></a>30.3.15 Memory management</H3>
<p>
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.
</p>
<p>
For example,
<div class="code"><pre>
%inline {
class A {
public:
A() { printf("A constructing\n"); }
~A() { printf("A destructing\n"); }
};
}
</pre></div>
<p>
Would produce this behavior in Octave:
</p>
<div class="targetlang"><pre>
octave:1> a=A();
A constructing
octave:2> b=a;
octave:3> clear a;
octave:4> b=4;
A destructing
</pre></div>
<p>
The %newobject directive may be used to control this behavior for pointers returned from functions.
<p>
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).
</p>
<H3><a name="Octave_nn25"></a>30.3.16 STL support</H3>
<p>
Various STL library files are provided for wrapping STL containers.
</p>
<H3><a name="Octave_nn26"></a>30.3.17 Matrix typemaps</H3>
<p>
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
</p>
<div class="code"><pre>
double my_det(const double* mat,int m,int n);
</pre></div>
<p>
that is accessed from Octave as,
</p>
<div class="targetlang"><pre>
octave:1> my_det(rand(4));
ans = -0.18388
</pre></div>
<tt><br></tt>
</body>
</html>
|
