23
23
<li><a href="#Typemaps_nn10">Typemap specifications</a>
25
<li><a href="#Typemaps_nn11">Defining a typemap</a>
25
<li><a href="#Typemaps_defining">Defining a typemap</a>
26
26
<li><a href="#Typemaps_nn12">Typemap scope</a>
27
27
<li><a href="#Typemaps_nn13">Copying a typemap</a>
28
28
<li><a href="#Typemaps_nn14">Deleting a typemap</a>
29
29
<li><a href="#Typemaps_nn15">Placement of typemaps</a>
31
<li><a href="#Typemaps_nn16">Pattern matching rules</a>
31
<li><a href="#Typemaps_pattern_matching">Pattern matching rules</a>
33
33
<li><a href="#Typemaps_nn17">Basic matching rules</a>
34
34
<li><a href="#Typemaps_nn18">Typedef reductions</a>
41
41
<li><a href="#Typemaps_nn22">Scope</a>
42
42
<li><a href="#Typemaps_nn23">Declaring new local variables</a>
43
43
<li><a href="#Typemaps_special_variables">Special variables</a>
44
<li><a href="#Typemaps_special_variable_macros">Special variable macros</a>
46
<li><a href="#Typemaps_special_macro_descriptor">$descriptor(type)</a>
47
<li><a href="#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
45
50
<li><a href="#Typemaps_nn25">Common typemap methods</a>
69
74
<li><a href="#runtime_type_checker">The run-time type checker</a>
71
76
<li><a href="#Typemaps_nn45">Implementation</a>
72
<li><a href="#Typemaps_nn46">Usage</a>
77
<li><a href="#Typemaps_runtime_type_checker_usage">Usage</a>
74
79
<li><a href="#Typemaps_overloading">Typemaps and overloading</a>
75
80
<li><a href="#Typemaps_nn48">More about <tt>%apply</tt> and <tt>%clear</tt></a>
76
81
<li><a href="#Typemaps_nn49">Reducing wrapper code size</a>
77
82
<li><a href="#Typemaps_nn47">Passing data between typemaps</a>
83
<li><a href="#Typemaps_nn52">C++ "this" pointer</a>
78
84
<li><a href="#Typemaps_nn51">Where to go for more information?</a>
224
226
However, there is really not much to it. The first typemap (the "in"
225
227
typemap) is used to convert a value from the target language to C. The second
226
228
typemap (the "out" typemap) is used to convert in the other
227
direction. The content of each typemap is a small fragment of C code
228
that is inserted directly into the SWIG generated wrapper functions. Within
229
this code, a number of special variables prefixed with a $ are expanded. These are
230
really just placeholders for C variables that are generated in the course
229
direction. The content of each typemap is a small fragment of code
230
that is inserted directly into the SWIG generated wrapper functions.
231
The code is usually C or C++ code which will be generated into the C/C++ wrapper functions.
232
Note that this isn't always the case as some target language modules allow target language
233
code within the typemaps which gets generated into target language specific files.
234
Within this code, a number of special variables prefixed with a $ are expanded. These are
235
really just placeholders for C/C++ variables that are generated in the course
231
236
of creating the wrapper function. In this case, <tt>$input</tt> refers to an
232
input object that needs to be converted to C and <tt>$result</tt>
237
input object that needs to be converted to C/C++ and <tt>$result</tt>
233
238
refers to an object that is going to be returned by a wrapper
234
function. <tt>$1</tt> refers to a C variable that has the same type as
239
function. <tt>$1</tt> refers to a C/C++ variable that has the same type as
235
240
specified in the typemap declaration (an <tt>int</tt> in this
1900
<H3><a name="Typemaps_special_variable_macros"></a>10.4.4 Special variable macros</H3>
1904
Special variable macros are like macro functions in that they take one or more input arguments
1905
which are used for the macro expansion.
1906
They look like macro/function calls but use the special variable <tt>$</tt> prefix to the macro name.
1907
Note that unlike normal macros, the expansion is not done by the preprocessor,
1908
it is done during the SWIG parsing/compilation stages.
1909
The following special variable macros are available across all language modules.
1912
<H4><a name="Typemaps_special_macro_descriptor"></a>10.4.4.1 $descriptor(type)</H4>
1916
This macro expands into the type descriptor structure for any C/C++ type specified in <tt>type</tt>.
1917
It behaves like the <tt>$1_descriptor</tt> special variable described above except that the type to expand is
1918
taken from the macro argument rather than inferred from the typemap type.
1919
For example, <tt>$descriptor(std::vector<int> *)</tt> will expand into <tt>SWIGTYPE_p_std__vectorT_int_t</tt>.
1920
This macro is mostly used in the scripting target languages and is demonstrated later in the <a href="#Typemaps_runtime_type_checker_usage">Run-time type checker usage</a> section.
1923
<H4><a name="Typemaps_special_macro_typemap"></a>10.4.4.2 $typemap(method, typepattern)</H4>
1927
This macro uses the <a href="#Typemaps_pattern_matching">pattern matching rules</a> described earlier to lookup and
1928
then substitute the special variable macro with the code in the matched typemap.
1929
The typemap to search for is specified by the arguments, where <tt>method</tt> is the typemap method name and
1930
<tt>typepattern</tt> is a type pattern as per the <tt>%typemap</tt> specification in the <a href="#Typemaps_defining">Defining a typemap</a> section.
1934
The special variables within the matched typemap are expanded into those for the matched typemap type,
1935
not the typemap within which the macro is called.
1936
In practice, there is little use for this macro in the scripting target languages.
1937
It is mostly used in the target languages that are statically typed as a way to obtain the target language type given the C/C++ type and more commonly only when the C++ type is a template parameter.
1941
The example below is for C# only and uses some typemap method names documented in the C# chapter, but it shows some of the possible syntax variations.
1946
%typemap(cstype) unsigned long "uint"
1947
%typemap(cstype) unsigned long bb "bool"
1948
%typemap(cscode) BarClass %{
1949
void foo($typemap(cstype, unsigned long aa) var1,
1950
$typemap(cstype, unsigned long bb) var2,
1951
$typemap(cstype, (unsigned long bb)) var3,
1952
$typemap(cstype, unsigned long) var4)
1961
The result is the following expansion
1966
%typemap(cstype) unsigned long "uint"
1967
%typemap(cstype) unsigned long bb "bool"
1968
%typemap(cscode) BarClass %{
1894
1980
<H2><a name="Typemaps_nn25"></a>10.5 Common typemap methods</H2>
2636
2722
The "out" typemap is the main typemap for return types.
2637
2723
This typemap supports an optional attribute flag called "optimal", which is for reducing
2638
temporary variables and the amount of generated code.
2639
It only really makes a difference when returning objects by value and it cannot always be used,
2724
temporary variables and the amount of generated code, thereby giving the compiler the opportunity to
2725
use <i>return value optimization</i> for generating faster executing code.
2726
It only really makes a difference when returning objects by value and has some limitations on usage,
2640
2727
as explained later on.
2694
2781
Note that three objects are being created as well as an assignment.
2695
2782
Wouldn't it be great if the <tt>XX::create()</tt> method was the only time a constructor was called?
2696
2783
As the method returns by value, this is asking a lot and the code that SWIG generates by default
2697
makes it impossible for the compiler to make this type of optimisation.
2784
makes it impossible for the compiler to use <i>return value optimisation (RVO)</i>.
2698
2785
However, this is where the "optimal" attribute in the "out" typemap can help out.
2699
2786
If the typemap code is kept the same and just the "optimal" attribute specified like this:
2754
2841
The major difference is the <tt>result</tt> temporary variable holding the value returned from <tt>XX::create()</tt> is no longer generated and instead the copy constructor call is made directly from
2755
2842
the value returned by <tt>XX::create()</tt>.
2756
With modern compiler optimisations turned on, the copy is not actually done, in fact the object is never created
2843
With modern compilers implementing RVO, the copy is not actually done, in fact the object is never created
2757
2844
on the stack in <tt>XX::create()</tt> at all, it is simply created directly on the heap.
2758
2845
In the first instance, the <tt>$1</tt> special variable in the typemap is expanded into <tt>result</tt>.
2759
2846
In the second instance, <tt>$1</tt> is expanded into <tt>XX::create()</tt> and this is essentially
2764
This kind of optimisation is not turned on by default as it has a number of restrictions.
2851
The "optimal" attribute optimisation is not turned on by default as it has a number of restrictions.
2765
2852
Firstly, some code cannot be condensed into a simple call for passing into the copy constructor.
2766
2853
One common occurrence is when <a href="Customization.html#exception">%exception</a> is used.
2767
2854
Consider adding the following <tt>%exception</tt> to the example:
3335
3422
Occasionally, you might need to write a typemap that needs to convert
3336
pointers of other types. To handle this, a special macro substitution
3337
<tt>$descriptor(type)</tt> can be used to generate the SWIG type
3423
pointers of other types. To handle this, the special variable macro
3424
<tt>$descriptor(type)</tt> covered earlier can be used to generate the SWIG type
3338
3425
descriptor name for any C datatype. For example:
3902
<H2><a name="Typemaps_nn51"></a>10.15 Where to go for more information?</H2>
3989
<H2><a name="Typemaps_nn52"></a>10.15 C++ "this" pointer</H2>
3993
All the rules discussed for Typemaps apply to C++ as well as C.
3994
However in addition C++ passes an extra parameter into every
3995
non-static class method -- the <tt>this</tt> pointer. Occasionally it can be
3996
useful to apply a typemap to this pointer (for example to check
3997
and make sure <tt>this</tt> is non-null before deferencing).
3998
Actually, C also has an the equivalent of the <tt>this</tt> pointer which is used
3999
when accessing variables in a C struct.
4002
In order to customise the <tt>this</tt> pointer handling, target a variable named <tt>self</tt> in your typemaps.
4003
<tt>self</tt> is the name SWIG uses to refer to the extra parameter in wrapped functions.
4006
For example, if wrapping for Java generation:
4011
%typemap(check) SWIGTYPE *self %{
4013
SWIG_JavaThrowException(jenv, SWIG_JavaNullPointerException, "swigCPtr null");
4021
In the above case, the <tt>$1</tt> variable is expanded into the argument
4022
name that SWIG is using as the <tt>this</tt> pointer.
4024
SWIG will then insert the check code before the actual C++ class method
4025
is called, and will raise an exception rather than crash
4026
the Java virtual machine.
4028
The generated code will look something like:
4034
SWIG_JavaThrowException(jenv, SWIG_JavaNullPointerException,
4035
"invalid native object; delete() likely already called");
4038
(arg1)->wrappedFunction(...);
4043
Note that if you have a parameter named <tt>self</tt> then it
4044
will also match the typemap. One work around is to create an interface file that wraps
4045
the method, but give the argument a name other than <tt>self</tt>.
4048
<H2><a name="Typemaps_nn51"></a>10.16 Where to go for more information?</H2>
added
removed
Doc/Manual/Typemaps.html
