-
Notifications
You must be signed in to change notification settings - Fork 1.2k
/
SWIGPlus.html
5105 lines (4293 loc) · 138 KB
/
SWIGPlus.html
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
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and C++</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#ffffff">
<H1><a name="SWIGPlus"></a>6 SWIG and C++</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#SWIGPlus_nn2">Comments on C++ Wrapping</a>
<li><a href="#SWIGPlus_nn3">Approach</a>
<li><a href="#SWIGPlus_nn4">Supported C++ features</a>
<li><a href="#SWIGPlus_nn5">Command line options and compilation</a>
<li><a href="#SWIGPlus_nn38">Proxy classes</a>
<ul>
<li><a href="#SWIGPlus_nn39">Construction of proxy classes</a>
<li><a href="#SWIGPlus_nn40">Resource management in proxies</a>
<li><a href="#SWIGPlus_nn41">Language specific details</a>
</ul>
<li><a href="#SWIGPlus_nn6">Simple C++ wrapping</a>
<ul>
<li><a href="#SWIGPlus_nn7">Constructors and destructors</a>
<li><a href="#SWIGPlus_nn8">Default constructors, copy constructors and implicit destructors</a>
<li><a href="#SWIGPlus_nn9">When constructor wrappers aren't created</a>
<li><a href="#SWIGPlus_nn10">Copy constructors</a>
<li><a href="#SWIGPlus_nn11">Member functions</a>
<li><a href="#SWIGPlus_nn12">Static members</a>
<li><a href="#SWIGPlus_member_data">Member data</a>
</ul>
<li><a href="#SWIGPlus_default_args">Default arguments</a>
<li><a href="#SWIGPlus_nn15">Protection</a>
<li><a href="#SWIGPlus_nn16">Enums and constants</a>
<li><a href="#SWIGPlus_nn17">Friends</a>
<li><a href="#SWIGPlus_nn18">References and pointers</a>
<li><a href="#SWIGPlus_nn19">Pass and return by value</a>
<li><a href="#SWIGPlus_nn20">Inheritance</a>
<li><a href="#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a>
<li><a href="#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a>
<ul>
<li><a href="#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="#SWIGPlus_nn28">Wrapping overloaded operators</a>
<li><a href="#SWIGPlus_class_extension">Class extension</a>
<li><a href="#SWIGPlus_nn30">Templates</a>
<li><a href="#SWIGPlus_namespaces">Namespaces</a>
<ul>
<li><a href="#SWIGPlus_nspace">The nspace feature for namespaces</a>
</ul>
<li><a href="#SWIGPlus_renaming_templated_types_namespaces">Renaming templated types in namespaces</a>
<li><a href="#SWIGPlus_exception_specifications">Exception specifications</a>
<li><a href="#SWIGPlus_catches">Exception handling with %catches</a>
<li><a href="#SWIGPlus_nn33">Pointers to Members</a>
<li><a href="#SWIGPlus_smart_pointers">Smart pointers and operator->()</a>
<li><a href="#SWIGPlus_ref_unref">C++ reference counted objects - ref/unref feature</a>
<li><a href="#SWIGPlus_nn35">Using declarations and inheritance</a>
<li><a href="#SWIGPlus_nested_classes">Nested classes</a>
<li><a href="#SWIGPlus_const">A brief rant about const-correctness</a>
<li><a href="#SWIGPlus_nn42">Where to go for more information</a>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support for wrapping C++. As a prerequisite,
you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see
how SWIG wraps ANSI C. Support for C++ builds upon ANSI C
wrapping and that material will be useful in understanding this chapter.
</p>
<H2><a name="SWIGPlus_nn2"></a>6.1 Comments on C++ Wrapping</H2>
<p>
Because of its complexity and the fact that C++ can be
difficult to integrate with itself let alone other languages, SWIG
only provides support for a subset of C++ features. Fortunately,
this is now a rather large subset.
</p>
<p>
In part, the problem with C++ wrapping is that there is no
semantically obvious (or automatic ) way to map many of its advanced
features into other languages. As a simple example, consider the
problem of wrapping C++ multiple inheritance to a target language with
no such support. Similarly, the use of overloaded operators and
overloaded functions can be problematic when no such capability exists
in a target language.
</p>
<p>
A more subtle issue with C++ has to do with the way that some C++
programmers think about programming libraries. In the world of SWIG,
you are really trying to create binary-level software components for
use in other languages. In order for this to work, a "component" has
to contain real executable instructions and there has to be some kind
of binary linking mechanism for accessing its functionality. In
contrast, C++ has increasingly relied upon generic programming and
templates for much of its functionality.
Although templates are a powerful feature, they are largely orthogonal
to the whole notion of binary components and libraries. For example,
an STL <tt>vector</tt> does not define any kind of binary object for
which SWIG can just create a wrapper. To further complicate matters,
these libraries often utilize a lot of behind the scenes magic in
which the semantics of seemingly basic operations (e.g., pointer
dereferencing, procedure call, etc.) can be changed in dramatic and
sometimes non-obvious ways. Although this "magic" may present few
problems in a C++-only universe, it greatly complicates the problem of
crossing language boundaries and provides many opportunities to shoot
yourself in the foot. You will just have to be careful.
</p>
<H2><a name="SWIGPlus_nn3"></a>6.2 Approach</H2>
<p>
To wrap C++, SWIG uses a layered approach to code generation.
At the lowest level, SWIG generates a collection of procedural ANSI-C style
wrappers. These wrappers take care of basic type conversion,
type checking, error handling, and other low-level details of the C++ binding.
These wrappers are also sufficient to bind C++ into any target language
that supports built-in procedures. In some sense, you might view this
layer of wrapping as providing a C library interface to C++.
On top of the low-level procedural (flattened) interface, SWIG generates proxy classes
that provide a natural object-oriented (OO) interface to the underlying code. The proxy classes are typically
written in the target language itself. For instance, in Python, a real
Python class is used to provide a wrapper around the underlying C++ object.
</p>
<p>
It is important to emphasize that SWIG takes a deliberately
conservative and non-intrusive approach to C++ wrapping. SWIG does not
encapsulate C++ classes inside a special C++ adaptor, it does not rely
upon templates, nor does it add in additional C++ inheritance when
generating wrappers. The last thing that most C++ programs need is
even more compiler magic. Therefore, SWIG tries to maintain a very
strict and clean separation between the implementation of your C++
application and the resulting wrapper code. You might say that SWIG
has been written to follow the principle of least surprise--it does
not play sneaky tricks with the C++ type system, it doesn't mess with
your class hierarchies, and it doesn't introduce new semantics.
Although this approach might not provide the most seamless integration
with C++, it is safe, simple, portable, and debuggable.
</p>
<p>
Some of this chapter focuses on the low-level procedural interface to
C++ that is used as the foundation for all language modules. Keep in
mind that the target languages also provide the high-level OO interface via
proxy classes. More detailed coverage can be found in the documentation
for each target language.
</p>
<H2><a name="SWIGPlus_nn4"></a>6.3 Supported C++ features</H2>
<p>
SWIG currently supports most C++ features including the following:</p>
<ul>
<li>Classes
<li>Constructors and destructors
<li>Virtual functions
<li>Public inheritance (including multiple inheritance)
<li>Static functions
<li>Function and method overloading
<li>Operator overloading for many standard operators
<li>References
<li>Templates (including specialization and member templates)
<li>Pointers to members
<li>Namespaces
<li>Default parameters
<li>Smart pointers
</ul>
<p>
The following C++ features are not currently supported:</p>
<ul>
<li>Overloaded versions of certain operators (new, delete, etc.)
</ul>
<p>
As a rule of thumb, SWIG should not be used on raw C++ source files, use header files only.
</p>
<p>
SWIG's C++ support is an ongoing project so some of these limitations may be lifted
in future releases. However, we make no promises. Also, submitting a bug report is a very
good way to get problems fixed (wink).
</p>
<H2><a name="SWIGPlus_nn5"></a>6.4 Command line options and compilation</H2>
<p>
When wrapping C++ code, it is critical that SWIG be called with the
`<tt>-c++</tt>' option. This changes the way a number of critical
features such as memory management are handled. It
also enables the recognition of C++ keywords. Without the <tt>-c++</tt>
flag, SWIG will either issue a warning or a large number of syntax
errors if it encounters C++ code in an interface file.</p>
<p>
When compiling and linking the resulting wrapper file, it is normal
to use the C++ compiler. For example:
</p>
<div class="shell">
<pre>
$ swig -c++ -tcl example.i
$ c++ -fPIC -c example_wrap.cxx
$ c++ example_wrap.o $(OBJS) -o example.so
</pre>
</div>
<p>
Unfortunately, the process varies slightly on each platform. Make sure
you refer to the documentation on each target language for further
details. The SWIG Wiki also has further details.
</p>
<b>Compatibility Note:</b> Early versions of SWIG generated just a flattened low-level C style API to C++ classes by default.
The <tt>-noproxy</tt> commandline option is recognised by many target languages and will generate just this
interface as in earlier versions.
<H2><a name="SWIGPlus_nn38"></a>6.5 Proxy classes</H2>
<p>
In order to provide a natural mapping from C++ classes to the target language classes, SWIG's target
languages mostly wrap C++ classes with special proxy classes. These
proxy classes are typically implemented in the target language itself.
For example, if you're building a Python module, each C++ class is
wrapped by a Python proxy class. Or if you're building a Java module, each
C++ class is wrapped by a Java proxy class.
</p>
<H3><a name="SWIGPlus_nn39"></a>6.5.1 Construction of proxy classes</H3>
<p>
Proxy classes are always constructed as an extra layer of wrapping that uses low-level
accessor functions. To illustrate, suppose you had a
C++ class like this:
</p>
<div class="code">
<pre>
class Foo {
public:
Foo();
~Foo();
int bar(int x);
int x;
};
</pre>
</div>
<p>
Using C++ as pseudocode, a proxy class looks something like this:
</p>
<div class="code">
<pre>
class FooProxy {
private:
Foo *self;
public:
FooProxy() {
self = new_Foo();
}
~FooProxy() {
delete_Foo(self);
}
int bar(int x) {
return Foo_bar(self,x);
}
int x_get() {
return Foo_x_get(self);
}
void x_set(int x) {
Foo_x_set(self,x);
}
};
</pre>
</div>
<p>
Of course, always keep in mind that the real proxy class is written in the target language.
For example, in Python, the proxy might look roughly like this:
</p>
<div class="targetlang">
<pre>
class Foo:
def __init__(self):
self.this = new_Foo()
def __del__(self):
delete_Foo(self.this)
def bar(self,x):
return Foo_bar(self.this,x)
def __getattr__(self,name):
if name == 'x':
return Foo_x_get(self.this)
...
def __setattr__(self,name,value):
if name == 'x':
Foo_x_set(self.this,value)
...
</pre>
</div>
<p>
Again, it's important to emphasize that the low-level accessor functions are always used by the
proxy classes.
Whenever possible, proxies try to take advantage of language features that are similar to C++. This
might include operator overloading, exception handling, and other features.
</p>
<H3><a name="SWIGPlus_nn40"></a>6.5.2 Resource management in proxies</H3>
<p>
A major issue with proxies concerns the memory management of wrapped objects. Consider the following
C++ code:
</p>
<div class="code">
<pre>
class Foo {
public:
Foo();
~Foo();
int bar(int x);
int x;
};
class Spam {
public:
Foo *value;
...
};
</pre>
</div>
<p>
Consider some script code that uses these classes:
</p>
<div class="targetlang">
<pre>
f = Foo() # Creates a new Foo
s = Spam() # Creates a new Spam
s.value = f # Stores a reference to f inside s
g = s.value # Returns stored reference
g = 4 # Reassign g to some other value
del f # Destroy f
</pre>
</div>
<p>
Now, ponder the resulting memory management issues. When objects are
created in the script, the objects are wrapped by newly created proxy
classes. That is, there is both a new proxy class instance and a new
instance of the underlying C++ class. In this example, both
<tt>f</tt> and <tt>s</tt> are created in this way. However, the
statement <tt>s.value</tt> is rather curious---when executed, a
pointer to <tt>f</tt> is stored inside another object. This means
that the scripting proxy class <em>AND</em> another C++ class share a
reference to the same object. To make matters even more interesting,
consider the statement <tt>g = s.value</tt>. When executed, this
creates a new proxy class <tt>g</tt> that provides a wrapper around the
C++ object stored in <tt>s.value</tt>. In general, there is no way to
know where this object came from---it could have been created by the
script, but it could also have been generated internally. In this
particular example, the assignment of <tt>g</tt> results in a second
proxy class for <tt>f</tt>. In other words, a reference to <tt>f</tt>
is now shared by two proxy classes <em>and</em> a C++ class.
</p>
<p>
Finally, consider what happens when objects are destroyed. In the
statement, <tt>g=4</tt>, the variable <tt>g</tt> is reassigned. In
many languages, this makes the old value of <tt>g</tt> available for
garbage collection. Therefore, this causes one of the proxy classes
to be destroyed. Later on, the statement <tt>del f</tt> destroys the
other proxy class. Of course, there is still a reference to the
original object stored inside another C++ object. What happens to it?
Is the object still valid?
</p>
<p>
To deal with memory management problems, proxy classes provide an API
for controlling ownership. In C++ pseudocode, ownership control might look
roughly like this:
</p>
<div class="code">
<pre>
class FooProxy {
public:
Foo *self;
int thisown;
FooProxy() {
self = new_Foo();
thisown = 1; // Newly created object
}
~FooProxy() {
if (thisown) delete_Foo(self);
}
...
// Ownership control API
void disown() {
thisown = 0;
}
void acquire() {
thisown = 1;
}
};
class FooPtrProxy: public FooProxy {
public:
FooPtrProxy(Foo *s) {
self = s;
thisown = 0;
}
};
class SpamProxy {
...
FooProxy *value_get() {
return FooPtrProxy(Spam_value_get(self));
}
void value_set(FooProxy *v) {
Spam_value_set(self,v->self);
v->disown();
}
...
};
</pre>
</div>
<p>
Looking at this code, there are a few central features:
</p>
<ul>
<li>Each proxy class keeps an extra flag to indicate ownership. C++ objects are only destroyed
if the ownership flag is set.
</li>
<li>When new objects are created in the target language, the ownership flag is set.
</li>
<li>When a reference to an internal C++ object is returned, it is wrapped by a proxy
class, but the proxy class does not have ownership.
</li>
<li>In certain cases, ownership is adjusted. For instance, when a value is assigned to the member of
a class, ownership is lost.
</li>
<li>Manual ownership control is provided by special <tt>disown()</tt> and <tt>acquire()</tt> methods.
</li>
</ul>
<p>
Given the tricky nature of C++ memory management, it is impossible for proxy classes to automatically handle
every possible memory management problem. However, proxies do provide a mechanism for manual control that
can be used (if necessary) to address some of the more tricky memory management problems.
</p>
<H3><a name="SWIGPlus_nn41"></a>6.5.3 Language specific details</H3>
<p>
Language specific details on proxy classes are contained in the chapters describing each target language. This
chapter has merely introduced the topic in a very general way.
</p>
<H2><a name="SWIGPlus_nn6"></a>6.6 Simple C++ wrapping</H2>
<p>
The following code shows a SWIG interface file for a simple C++
class.</p>
<div class="code"><pre>
%module list
%{
#include "list.h"
%}
// Very simple C++ example for linked list
class List {
public:
List();
~List();
int search(char *value);
void insert(char *);
void remove(char *);
char *get(int n);
int length;
static void print(List *l);
};
</pre></div>
<p>
To generate wrappers for this class, SWIG first reduces the class to a collection of low-level C-style
accessor functions which are then used by the proxy classes.
</p>
<H3><a name="SWIGPlus_nn7"></a>6.6.1 Constructors and destructors</H3>
<p>
C++ constructors and destructors are translated into accessor
functions such as the following :</p>
<div class="code"><pre>
List * new_List(void) {
return new List;
}
void delete_List(List *l) {
delete l;
}
</pre></div>
<H3><a name="SWIGPlus_nn8"></a>6.6.2 Default constructors, copy constructors and implicit destructors</H3>
<p>
Following the C++ rules for implicit constructor and destructors, SWIG
will automatically assume there is one even when they are not
explicitly declared in the class interface.
</p>
<p>
In general then:
</p>
<ul>
<li>
If a C++ class does not declare any explicit constructor, SWIG will
automatically generate a wrapper for one.
</li>
<li>
If a C++ class does not declare an explicit copy constructor, SWIG will
automatically generate a wrapper for one if the <tt>%copyctor</tt> is used.
</li>
<li>
If a C++ class does not declare an explicit destructor, SWIG will
automatically generate a wrapper for one.
</li>
</ul>
<p>
And as in C++, a few rules that alters the previous behavior:
</p>
<ul>
<li>A default constructor is not created if a class already defines a constructor with arguments.
</li>
<li>Default constructors are not generated for classes with pure virtual methods or for classes that
inherit from an abstract class, but don't provide definitions for all of the pure methods.
</li>
<li>A default constructor is not created unless all base classes support a
default constructor.
</li>
<li>Default constructors and implicit destructors are not created if a class
defines them in a <tt>private</tt> or <tt>protected</tt> section.
</li>
<li>Default constructors and implicit destructors are not created if any base
class defines a non-public default constructor or destructor.
</li>
</ul>
<p>
SWIG should never generate a default constructor, copy constructor or
default destructor wrapper for a class in which it is illegal to do so. In
some cases, however, it could be necessary (if the complete class
declaration is not visible from SWIG, and one of the above rules is
violated) or desired (to reduce the size of the final interface) by
manually disabling the implicit constructor/destructor generation.
</p>
<p>
To manually disable these, the <tt>%nodefaultctor</tt> and <tt>%nodefaultdtor</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a> directives
can be used. Note that these directives only affects the
implicit generation, and they have no effect if the default/copy
constructors or destructor are explicitly declared in the class
interface.
</p>
<p>
For example:
</p>
<div class="code">
<pre>
%nodefaultctor Foo; // Disable the default constructor for class Foo.
class Foo { // No default constructor is generated, unless one is declared
...
};
class Bar { // A default constructor is generated, if possible
...
};
</pre>
</div>
<p>
The directive <tt>%nodefaultctor</tt> can also be applied "globally", as in:
</p>
<div class="code">
<pre>
%nodefaultctor; // Disable creation of default constructors
class Foo { // No default constructor is generated, unless one is declared
...
};
class Bar {
public:
Bar(); // The default constructor is generated, since one is declared
};
%clearnodefaultctor; // Enable the creation of default constructors again
</pre>
</div>
<p>
The corresponding <tt>%nodefaultdtor</tt> directive can be used
to disable the generation of the default or implicit destructor, if
needed. Be aware, however, that this could lead to memory leaks in the
target language. Hence, it is recommended to use this directive only
in well known cases. For example:
</p>
<div class="code">
<pre>
%nodefaultdtor Foo; // Disable the implicit/default destructor for class Foo.
class Foo { // No destructor is generated, unless one is declared
...
};
</pre>
</div>
<p>
<b>Compatibility Note:</b> The generation of default
constructors/implicit destructors was made the default behavior in SWIG
1.3.7. This may break certain older modules, but the old behavior can
be easily restored using <tt>%nodefault</tt> or the
<tt>-nodefault</tt> command line option. Furthermore, in order for
SWIG to properly generate (or not generate) default constructors, it
must be able to gather information from both the <tt>private</tt> and
<tt>protected</tt> sections (specifically, it needs to know if a private or
protected constructor/destructor is defined). In older versions of
SWIG, it was fairly common to simply remove or comment out
the private and protected sections of a class due to parser limitations.
However, this removal may now cause SWIG to erroneously generate constructors
for classes that define a constructor in those sections. Consider restoring
those sections in the interface or using <tt>%nodefault</tt> to fix the problem.
</p>
<p>
<b>Note:</b> The <tt>%nodefault</tt>
directive/<tt>-nodefault</tt> options described above, which disable both the default
constructor and the implicit destructors, could lead to memory
leaks, and so it is strongly recommended to not use them.
</p>
<H3><a name="SWIGPlus_nn9"></a>6.6.3 When constructor wrappers aren't created</H3>
<p>
If a class defines a constructor, SWIG normally tries to generate a wrapper for it. However, SWIG will
not generate a constructor wrapper if it thinks that it will result in illegal wrapper code. There are really
two cases where this might show up.
</p>
<p>
First, SWIG won't generate wrappers for protected or private constructors. For example:
</p>
<div class="code">
<pre>
class Foo {
protected:
Foo(); // Not wrapped.
public:
...
};
</pre>
</div>
<p>
Next, SWIG won't generate wrappers for a class if it appears to be abstract--that is, it has undefined
pure virtual methods. Here are some examples:
</p>
<div class="code">
<pre>
class Bar {
public:
Bar(); // Not wrapped. Bar is abstract.
virtual void spam(void) = 0;
};
class Grok : public Bar {
public:
Grok(); // Not wrapped. No implementation of abstract spam().
};
</pre>
</div>
<p>
Some users are surprised (or confused) to find missing constructor wrappers in their interfaces. In almost
all cases, this is caused when classes are determined to be abstract. To see if this is the case, run SWIG with
all of its warnings turned on:
</p>
<div class="shell">
<pre>
% swig -Wall -python module.i
</pre>
</div>
<p>
In this mode, SWIG will issue a warning for all abstract classes. It is possible to force a class to be
non-abstract using this:
</p>
<div class="code">
<pre>
%feature("notabstract") Foo;
class Foo : public Bar {
public:
Foo(); // Generated no matter what---not abstract.
...
};
</pre>
</div>
<p>
More information about <tt>%feature</tt> can be found in the <a href="Customization.html#Customization">Customization features</a> chapter.
</p>
<H3><a name="SWIGPlus_nn10"></a>6.6.4 Copy constructors</H3>
<p>
If a class defines more than one constructor, its behavior depends on the capabilities of the
target language. If overloading is supported, the copy constructor is accessible using
the normal constructor function. For example, if you have this:
</p>
<div class="code">
<pre>
class List {
public:
List();
List(const List &); // Copy constructor
...
};
</pre>
</div>
<p>
then the copy constructor can be used as follows:
</p>
<div class="targetlang">
<pre>
x = List() # Create a list
y = List(x) # Copy list x
</pre>
</div>
<p>
If the target language does not support overloading, then the copy constructor is available
through a special function like this:
</p>
<div class="code">
<pre>
List *copy_List(List *f) {
return new List(*f);
}
</pre>
</div>
<p>
<b>Note:</b> For a class <tt>X</tt>, SWIG only treats a constructor as
a copy constructor if it can be applied to an object of type
<tt>X</tt> or <tt>X *</tt>. If more than one copy constructor is
defined, only the first definition that appears is used as the copy
constructor--other definitions will result in a name-clash.
Constructors such as <tt>X(const X &)</tt>, <tt>X(X &)</tt>, and
<tt>X(X *)</tt> are handled as copy constructors in SWIG.
</p>
<p>
<b>Note:</b> SWIG does <em>not</em> generate a copy constructor
wrapper unless one is explicitly declared in the class. This differs
from the treatment of default constructors and destructors.
However, copy constructor wrappers can be generated if using the <tt>copyctor</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a>. For example:
</p>
<div class="code">
<pre>
%copyctor List;
class List {
public:
List();
};
</pre>
</div>
<p>
Will generate a copy constructor wrapper for <tt>List</tt>.
</p>
<p>
<b>Compatibility note:</b> Special support for copy constructors was
not added until SWIG-1.3.12. In previous versions, copy constructors
could be wrapped, but they had to be renamed. For example:
</p>
<div class="code">
<pre>
class Foo {
public:
Foo();
%name(CopyFoo) Foo(const Foo &);
...
};
</pre>
</div>
<p>
For backwards compatibility, SWIG does not perform any special
copy-constructor handling if the constructor has been manually
renamed. For instance, in the above example, the name of the
constructor is set to <tt>new_CopyFoo()</tt>. This is the same as in
older versions.
</p>
<H3><a name="SWIGPlus_nn11"></a>6.6.5 Member functions</H3>
<p>
All member functions are roughly translated into accessor functions like this :</p>
<div class="code"><pre>
int List_search(List *obj, char *value) {
return obj->search(value);
}
</pre></div>
<p>
This translation is the same even if the member function has been
declared as <tt>virtual</tt>.
</p>
<p>
It should be noted that SWIG does not <em>actually</em> create a C accessor
function in the code it generates. Instead, member access such as
<tt>obj->search(value)</tt> is directly inlined into the generated
wrapper functions. However, the name and calling convention of the
low-level procedural wrappers match the accessor function prototype described above.
</p>
<H3><a name="SWIGPlus_nn12"></a>6.6.6 Static members</H3>
<p>
Static member functions are called directly without making any special
transformations. For example, the static member function
<tt>print(List *l)</tt> directly invokes <tt>List::print(List *l)</tt>
in the generated wrapper code.
</p>
<H3><a name="SWIGPlus_member_data"></a>6.6.7 Member data</H3>
<p>
Member data is handled in exactly the same manner as for C
structures. A pair of accessor functions are effectively created. For example
:</p>
<div class="code"><pre>
int List_length_get(List *obj) {
return obj->length;
}
int List_length_set(List *obj, int value) {
obj->length = value;
return value;
}
</pre></div>
<p>
A read-only member can be created using the <tt>%immutable</tt> and <tt>%mutable</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a> directive.
For example, we probably wouldn't want
the user to change the length of a list so we could do the following
to make the value available, but read-only.</p>
<div class="code"><pre>
class List {
public:
...
%immutable;
int length;
%mutable;
...
};
</pre></div>
<p>
Alternatively, you can specify an immutable member in advance like this:
</p>
<div class="code">
<pre>
%immutable List::length;
...
class List {
...
int length; // Immutable by above directive
...
};
</pre>
</div>
<p>
Similarly, all data attributes declared as <tt>const</tt> are wrapped as read-only members.
</p>
<p>
By default, SWIG uses the const reference typemaps for members that are primitive types.
There are some subtle issues when wrapping data members that are
not primitive types, such as classes. For instance, if you had another class like this,
</p>
<div class="code">
<pre>
class Foo {
public:
List items;
...
</pre>
</div>
<p>
then the low-level accessor to the <tt>items</tt> member actually uses pointers.
For example:
</p>
<div class="code">
<pre>
List *Foo_items_get(Foo *self) {
return &self->items;
}
void Foo_items_set(Foo *self, List *value) {
self->items = *value;
}
</pre>
</div>
<p>
More information about this can be found in the SWIG Basics chapter,
<a href="SWIG.html#SWIG_structure_data_members">Structure data members</a> section.
</p>
<p>
The wrapper code to generate the accessors for classes comes from the pointer typemaps.
This can be somewhat unnatural for some types.
For example, a user would expect the STL std::string class member variables to be wrapped as a string in the target language,