jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add C++20 documentation chapter

Browse source 
[skip-ci]
This commit is contained in:
William S Fulton 2020-01-28 20:31:15 +00:00
commit 36e8d521de
35 changed files with 1045 additions and 1029 deletions
Download patch file Download diff file Expand all files Collapse all files

132
Doc/Manual/Typemaps.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Typemaps">13 Typemaps</a></H1>
<H1><a name="Typemaps">14 Typemaps</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -102,7 +102,7 @@
<H2><a name="Typemaps_nn2">13.1 Introduction</a></H2>
<H2><a name="Typemaps_nn2">14.1 Introduction</a></H2>
<p>
@ -119,7 +119,7 @@ to re-read the earlier chapters if you have found your way to this
chapter with only a vague idea of what SWIG already does by default.
</p>
<H3><a name="Typemaps_nn3">13.1.1 Type conversion</a></H3>
<H3><a name="Typemaps_nn3">14.1.1 Type conversion</a></H3>
<p>
@ -212,7 +212,7 @@ to read the extension documentation for your favorite language to know
how it works (an exercise left to the reader).
</p>
<H3><a name="Typemaps_nn4">13.1.2 Typemaps</a></H3>
<H3><a name="Typemaps_nn4">14.1.2 Typemaps</a></H3>
<p>
@ -313,7 +313,7 @@ parts of the generated wrapper functions. Because arbitrary code can be insert
possible to completely change the way in which values are converted.
</p>
<H3><a name="Typemaps_nn5">13.1.3 Pattern matching</a></H3>
<H3><a name="Typemaps_nn5">14.1.3 Pattern matching</a></H3>
<p>
@ -415,7 +415,7 @@ In this case, a single input object is expanded into a pair of C arguments. Thi
provides a hint to the unusual variable naming scheme involving <tt>$1</tt>, <tt>$2</tt>, and so forth.
</p>
<H3><a name="Typemaps_nn6">13.1.4 Reusing typemaps</a></H3>
<H3><a name="Typemaps_nn6">14.1.4 Reusing typemaps</a></H3>
<p>
@ -493,7 +493,7 @@ typedef int size_t;
then SWIG already knows that the <tt>int</tt> typemaps apply. You don't have to do anything.
</p>
<H3><a name="Typemaps_nn7">13.1.5 What can be done with typemaps?</a></H3>
<H3><a name="Typemaps_nn7">14.1.5 What can be done with typemaps?</a></H3>
<p>
@ -605,7 +605,7 @@ typemaps that expand upon this list. For example, the Java module defines a var
aspects of the Java bindings. Consult language specific documentation for further details.
</p>
<H3><a name="Typemaps_nn8">13.1.6 What can't be done with typemaps?</a></H3>
<H3><a name="Typemaps_nn8">14.1.6 What can't be done with typemaps?</a></H3>
<p>
@ -668,7 +668,7 @@ void wrap_foo(char *s, int x) {
</pre>
</div>
<H3><a name="Typemaps_aspects">13.1.7 Similarities to Aspect Oriented Programming</a></H3>
<H3><a name="Typemaps_aspects">14.1.7 Similarities to Aspect Oriented Programming</a></H3>
<p>
@ -686,7 +686,7 @@ SWIG can also be viewed as has having a second set of aspects based around <a hr
Features such as <tt>%exception</tt> are also cross-cutting concerns as they encapsulate code that can be used to add logging or exception handling to any function.
</p>
<H3><a name="Typemaps_nn9">13.1.8 The rest of this chapter</a></H3>
<H3><a name="Typemaps_nn9">14.1.8 The rest of this chapter</a></H3>
<p>
@ -706,14 +706,14 @@ of "The C Programming Language" by Kernighan and Ritchie or
"The C++ Programming Language" by Stroustrup before going any further.
</p>
<H2><a name="Typemaps_nn10">13.2 Typemap specifications</a></H2>
<H2><a name="Typemaps_nn10">14.2 Typemap specifications</a></H2>
<p>
This section describes the behavior of the <tt>%typemap</tt> directive itself.
</p>
<H3><a name="Typemaps_defining">13.2.1 Defining a typemap</a></H3>
<H3><a name="Typemaps_defining">14.2.1 Defining a typemap</a></H3>
<p>
@ -826,7 +826,7 @@ Admittedly, it's not the most readable syntax at first glance. However, the pur
individual pieces will become clear.
</p>
<H3><a name="Typemaps_nn12">13.2.2 Typemap scope</a></H3>
<H3><a name="Typemaps_nn12">14.2.2 Typemap scope</a></H3>
<p>
@ -876,7 +876,7 @@ class Foo {
</pre>
</div>
<H3><a name="Typemaps_nn13">13.2.3 Copying a typemap</a></H3>
<H3><a name="Typemaps_nn13">14.2.3 Copying a typemap</a></H3>
<p>
@ -934,7 +934,7 @@ The patterns for <tt>%apply</tt> follow the same rules as for <tt>%typemap</tt>.
</pre>
</div>
<H3><a name="Typemaps_nn14">13.2.4 Deleting a typemap</a></H3>
<H3><a name="Typemaps_nn14">14.2.4 Deleting a typemap</a></H3>
<p>
@ -968,7 +968,7 @@ For example:
after the clear operation.
</p>
<H3><a name="Typemaps_nn15">13.2.5 Placement of typemaps</a></H3>
<H3><a name="Typemaps_nn15">14.2.5 Placement of typemaps</a></H3>
<p>
@ -1048,7 +1048,7 @@ It should be noted that for scoping to work, SWIG has to know that <tt>string</t
within a particular namespace. In this example, this is done using the forward class declaration <tt>class string</tt>.
</p>
<H2><a name="Typemaps_pattern_matching">13.3 Pattern matching rules</a></H2>
<H2><a name="Typemaps_pattern_matching">14.3 Pattern matching rules</a></H2>
<p>
@ -1056,7 +1056,7 @@ The section describes the pattern matching rules by which C/C++ datatypes are as
The matching rules can be observed in practice by using the debugging options also described.
</p>
<H3><a name="Typemaps_nn17">13.3.1 Basic matching rules</a></H3>
<H3><a name="Typemaps_nn17">14.3.1 Basic matching rules</a></H3>
<p>
@ -1155,7 +1155,7 @@ void F(int x[1000]); // int [ANY] rule (typemap 5)
stripped all qualifiers in one step.
</p>
<H3><a name="Typemaps_typedef_reductions">13.3.2 Typedef reductions matching</a></H3>
<H3><a name="Typemaps_typedef_reductions">14.3.2 Typedef reductions matching</a></H3>
<p>
@ -1330,7 +1330,7 @@ void go(Struct aStruct);
</pre>
</div>
<H3><a name="Typemaps_nn19">13.3.3 Default typemap matching rules</a></H3>
<H3><a name="Typemaps_nn19">14.3.3 Default typemap matching rules</a></H3>
<p>
@ -1468,7 +1468,7 @@ Finally the best way to view the typemap matching rules in action is via the <a
simpler scheme to match the current C++ class template partial specialization matching rules.
</p>
<H3><a name="Typemaps_multi_argument_typemaps_patterns">13.3.4 Multi-arguments typemaps</a></H3>
<H3><a name="Typemaps_multi_argument_typemaps_patterns">14.3.4 Multi-arguments typemaps</a></H3>
<p>
@ -1498,7 +1498,7 @@ but all subsequent arguments must match exactly.
</p>
<H3><a name="Typemaps_matching_template_comparison">13.3.5 Matching rules compared to C++ templates</a></H3>
<H3><a name="Typemaps_matching_template_comparison">14.3.5 Matching rules compared to C++ templates</a></H3>
<p>
@ -1657,7 +1657,7 @@ are similar to those for specialized template handling.
</p>
<H3><a name="Typemaps_debugging_search">13.3.6 Debugging typemap pattern matching</a></H3>
<H3><a name="Typemaps_debugging_search">14.3.6 Debugging typemap pattern matching</a></H3>
<p>
@ -1870,7 +1870,7 @@ Also the types may be displayed slightly differently - <tt>char const *</tt> and
</li>
</ul>
<H2><a name="Typemaps_nn21">13.4 Code generation rules</a></H2>
<H2><a name="Typemaps_nn21">14.4 Code generation rules</a></H2>
<p>
@ -1878,7 +1878,7 @@ This section describes rules by which typemap code is inserted into
the generated wrapper code.
</p>
<H3><a name="Typemaps_nn22">13.4.1 Scope</a></H3>
<H3><a name="Typemaps_nn22">14.4.1 Scope</a></H3>
<p>
@ -1956,7 +1956,7 @@ a block scope when it is emitted. This sometimes results in a less complicated
Note that only the third of the three typemaps have the typemap code passed through the SWIG preprocessor.
</p>
<H3><a name="Typemaps_nn23">13.4.2 Declaring new local variables</a></H3>
<H3><a name="Typemaps_nn23">14.4.2 Declaring new local variables</a></H3>
<p>
@ -2123,7 +2123,7 @@ each type must have its own local variable declaration.
</div>
<H3><a name="Typemaps_special_variables">13.4.3 Special variables</a></H3>
<H3><a name="Typemaps_special_variables">14.4.3 Special variables</a></H3>
<p>
@ -2375,7 +2375,7 @@ Another approach, which only works for arrays is to use the <tt>$1_basetype</tt>
</pre>
</div>
<H3><a name="Typemaps_special_variable_macros">13.4.4 Special variable macros</a></H3>
<H3><a name="Typemaps_special_variable_macros">14.4.4 Special variable macros</a></H3>
<p>
@ -2387,7 +2387,7 @@ it is done during the SWIG parsing/compilation stages.
The following special variable macros are available across all language modules.
</p>
<H4><a name="Typemaps_special_macro_descriptor">13.4.4.1 $descriptor(type)</a></H4>
<H4><a name="Typemaps_special_macro_descriptor">14.4.4.1 $descriptor(type)</a></H4>
<p>
@ -2398,7 +2398,7 @@ For example, <tt>$descriptor(std::vector&lt;int&gt; *)</tt> will expand into <tt
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.
</p>
<H4><a name="Typemaps_special_macro_typemap">13.4.4.2 $typemap(method, typepattern)</a></H4>
<H4><a name="Typemaps_special_macro_typemap">14.4.4.2 $typemap(method, typepattern)</a></H4>
<p>
@ -2456,7 +2456,7 @@ The result is the following expansion
</div>
<H3><a name="Typemaps_special_variable_attributes">13.4.5 Special variables and typemap attributes</a></H3>
<H3><a name="Typemaps_special_variable_attributes">14.4.5 Special variables and typemap attributes</a></H3>
<p>
@ -2483,7 +2483,7 @@ is equivalent to the following as <tt>$*1_ltype</tt> expands to <tt>unsigned int
</pre>
</div>
<H3><a name="Typemaps_special_variables_and_macros">13.4.6 Special variables combined with special variable macros</a></H3>
<H3><a name="Typemaps_special_variables_and_macros">14.4.6 Special variables combined with special variable macros</a></H3>
<p>
@ -2525,7 +2525,7 @@ which then expands to:
</div>
<H2><a name="Typemaps_nn25">13.5 Common typemap methods</a></H2>
<H2><a name="Typemaps_nn25">14.5 Common typemap methods</a></H2>
<p>
@ -2533,7 +2533,7 @@ The family of typemaps recognized by a language module may vary. However,
the following typemap methods are nearly universal:
</p>
<H3><a name="Typemaps_nn26">13.5.1 "in" typemap</a></H3>
<H3><a name="Typemaps_nn26">14.5.1 "in" typemap</a></H3>
<p>
@ -2593,7 +2593,7 @@ Usually <tt>numinputs</tt> is not specified, whereupon the default value is 1, t
is the same as the old "ignore" typemap.
</p>
<H3><a name="Typemaps_nn27">13.5.2 "typecheck" typemap</a></H3>
<H3><a name="Typemaps_nn27">14.5.2 "typecheck" typemap</a></H3>
<p>
@ -2620,7 +2620,7 @@ If you define new "in" typemaps <em>and</em> your program uses overloaded method
"typecheck" typemaps. More details about this follow in the <a href="#Typemaps_overloading">Typemaps and overloading</a> section.
</p>
<H3><a name="Typemaps_nn28">13.5.3 "out" typemap</a></H3>
<H3><a name="Typemaps_nn28">14.5.3 "out" typemap</a></H3>
<p>
@ -2651,7 +2651,7 @@ $symname - Name of function/method being wrapped
The "out" typemap supports an optional attribute flag called "optimal". This is for code optimisation and is detailed in the <a href="#Typemaps_optimal">Optimal code generation when returning by value</a> section.
</p>
<H3><a name="Typemaps_nn29">13.5.4 "arginit" typemap</a></H3>
<H3><a name="Typemaps_nn29">14.5.4 "arginit" typemap</a></H3>
<p>
@ -2670,7 +2670,7 @@ For example:
</pre>
</div>
<H3><a name="Typemaps_nn30">13.5.5 "default" typemap</a></H3>
<H3><a name="Typemaps_nn30">14.5.5 "default" typemap</a></H3>
<p>
@ -2703,7 +2703,7 @@ See the <a href="SWIG.html#SWIG_default_args">Default/optional arguments</a> sec
for further information on default argument wrapping.
</p>
<H3><a name="Typemaps_nn31">13.5.6 "check" typemap</a></H3>
<H3><a name="Typemaps_nn31">14.5.6 "check" typemap</a></H3>
<p>
@ -2722,7 +2722,7 @@ converted. For example:
</pre>
</div>
<H3><a name="Typemaps_nn32">13.5.7 "argout" typemap</a></H3>
<H3><a name="Typemaps_nn32">14.5.7 "argout" typemap</a></H3>
<p>
@ -2768,7 +2768,7 @@ return values are often appended to return value of the function.
See the <tt>typemaps.i</tt> library file for examples.
</p>
<H3><a name="Typemaps_nn33">13.5.8 "freearg" typemap</a></H3>
<H3><a name="Typemaps_nn33">14.5.8 "freearg" typemap</a></H3>
<p>
@ -2801,7 +2801,7 @@ be used in other typemaps whenever a wrapper function needs to abort
prematurely.
</p>
<H3><a name="Typemaps_nn34">13.5.9 "newfree" typemap</a></H3>
<H3><a name="Typemaps_nn34">14.5.9 "newfree" typemap</a></H3>
<p>
@ -2830,7 +2830,7 @@ string *foo();
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for further details.
</p>
<H3><a name="Typemaps_ret">13.5.10 "ret" typemap</a></H3>
<H3><a name="Typemaps_ret">14.5.10 "ret" typemap</a></H3>
<p>
@ -2869,7 +2869,7 @@ This approach is an alternative to using the "newfree" typemap and <tt>%newobjec
is no need to list all the functions that require the memory cleanup, it is purely done on types.
</p>
<H3><a name="Typemaps_nn35">13.5.11 "memberin" typemap</a></H3>
<H3><a name="Typemaps_nn35">14.5.11 "memberin" typemap</a></H3>
<p>
@ -2891,7 +2891,7 @@ It is rarely necessary to write "memberin" typemaps---SWIG already provides
a default implementation for arrays, strings, and other objects.
</p>
<H3><a name="Typemaps_nn36">13.5.12 "varin" typemap</a></H3>
<H3><a name="Typemaps_nn36">14.5.12 "varin" typemap</a></H3>
<p>
@ -2899,7 +2899,7 @@ The "varin" typemap is used to convert objects in the target language to C for t
purposes of assigning to a C/C++ global variable. This is implementation specific.
</p>
<H3><a name="Typemaps_nn37">13.5.13 "varout" typemap</a></H3>
<H3><a name="Typemaps_nn37">14.5.13 "varout" typemap</a></H3>
<p>
@ -2907,7 +2907,7 @@ The "varout" typemap is used to convert a C/C++ object to an object in the targe
language when reading a C/C++ global variable. This is implementation specific.
</p>
<H3><a name="Typemaps_throws_typemap">13.5.14 "throws" typemap</a></H3>
<H3><a name="Typemaps_throws_typemap">14.5.14 "throws" typemap</a></H3>
<p>
@ -2957,7 +2957,7 @@ Note that if your methods do not have an exception specification but they do thr
Please also see the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section for another way to handle exceptions.
</p>
<H2><a name="Typemaps_nn39">13.6 Some typemap examples</a></H2>
<H2><a name="Typemaps_nn39">14.6 Some typemap examples</a></H2>
<p>
@ -2965,7 +2965,7 @@ This section contains a few examples. Consult language module documentation
for more examples.
</p>
<H3><a name="Typemaps_nn40">13.6.1 Typemaps for arrays</a></H3>
<H3><a name="Typemaps_nn40">14.6.1 Typemaps for arrays</a></H3>
<p>
@ -3224,7 +3224,7 @@ Now, you will find that member access is quite nice:
useless and has since been eliminated. To return structure members, simply use the "out" typemap.
</p>
<H3><a name="Typemaps_nn41">13.6.2 Implementing constraints with typemaps</a></H3>
<H3><a name="Typemaps_nn41">14.6.2 Implementing constraints with typemaps</a></H3>
<p>
@ -3272,7 +3272,7 @@ a NULL pointer. As a result, SWIG can often prevent a potential
segmentation faults or other run-time problems by raising an exception
rather than blindly passing values to the underlying C/C++ program.</p>
<H2><a name="Typemaps_nn43">13.7 Typemaps for multiple target languages</a></H2>
<H2><a name="Typemaps_nn43">14.7 Typemaps for multiple target languages</a></H2>
<p>
@ -3302,7 +3302,7 @@ The example above also shows a common approach of issuing a warning for an as ye
<tt>%typemap(ruby, in) int "$1 = NUM2INT($input);"</tt>.
</p>
<H2><a name="Typemaps_optimal">13.8 Optimal code generation when returning by value</a></H2>
<H2><a name="Typemaps_optimal">14.8 Optimal code generation when returning by value</a></H2>
<p>
@ -3491,7 +3491,7 @@ example.i:7: Warning 475: optimal attribute usage in the out typemap.
However, it doesn't always get it right, for example when <tt>$1</tt> is within some commented out code.
</p>
<H2><a name="Typemaps_multi_argument_typemaps">13.9 Multi-argument typemaps</a></H2>
<H2><a name="Typemaps_multi_argument_typemaps">14.9 Multi-argument typemaps</a></H2>
<p>
@ -3768,7 +3768,7 @@ with non-consecutive C/C++ arguments; a workaround such as a helper function re-
the arguments to make them consecutive will need to be written.
</p>
<H2><a name="Typemaps_warnings">13.10 Typemap warnings</a></H2>
<H2><a name="Typemaps_warnings">14.10 Typemap warnings</a></H2>
<p>
@ -3777,7 +3777,7 @@ See the information in the <a href="Warnings.html#Warnings_nn5">issuing warnings
</p>
<H2><a name="Typemaps_fragments">13.11 Typemap fragments</a></H2>
<H2><a name="Typemaps_fragments">14.11 Typemap fragments</a></H2>
<p>
@ -4113,7 +4113,7 @@ fragment usage unless a desire to really get to grips
with some powerful but tricky macro and fragment usage that is used in parts of the SWIG typemap library.
</p>
<H3><a name="Typemaps_fragment_type_specialization">13.11.1 Fragment type specialization</a></H3>
<H3><a name="Typemaps_fragment_type_specialization">14.11.1 Fragment type specialization</a></H3>
<p>
@ -4146,7 +4146,7 @@ struct A {
</pre>
</div>
<H3><a name="Typemaps_automatic_specialization">13.11.2 Fragments and automatic typemap specialization</a></H3>
<H3><a name="Typemaps_automatic_specialization">14.11.2 Fragments and automatic typemap specialization</a></H3>
<p>
@ -4192,7 +4192,7 @@ The interested (or very brave) reader can take a look at the fragments.swg file
</p>
<H2><a name="Typemaps_runtime_type_checker">13.12 The run-time type checker</a></H2>
<H2><a name="Typemaps_runtime_type_checker">14.12 The run-time type checker</a></H2>
<p>
@ -4218,7 +4218,7 @@ language modules.</li>
<li>Modules can be unloaded from the type system.</li>
</ul>
<H3><a name="Typemaps_nn45">13.12.1 Implementation</a></H3>
<H3><a name="Typemaps_nn45">14.12.1 Implementation</a></H3>
<p>
@ -4412,7 +4412,7 @@ structures rather than creating new ones. These <tt>swig_module_info</tt>
structures are chained together in a circularly linked list.
</p>
<H3><a name="Typemaps_runtime_type_checker_usage">13.12.2 Usage</a></H3>
<H3><a name="Typemaps_runtime_type_checker_usage">14.12.2 Usage</a></H3>
<p>This section covers how to use these functions from typemaps. To learn how to
@ -4508,7 +4508,7 @@ probably just look at the output of SWIG to get a better sense for how types are
managed.
</p>
<H2><a name="Typemaps_overloading">13.13 Typemaps and overloading</a></H2>
<H2><a name="Typemaps_overloading">14.13 Typemaps and overloading</a></H2>
<p>
@ -4847,7 +4847,7 @@ Subsequent "in" typemaps would then perform more extensive type-checking.
</li>
</ul>
<H3><a name="Typemaps_typecheck_pointer">13.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a></H3>
<H3><a name="Typemaps_typecheck_pointer">14.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a></H3>
<p>
@ -4949,7 +4949,7 @@ Otherwise both can be wrapped by removing the overloading name ambiguity by rena
The 'equivalent' attribute is used in the implementation for the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> library.
</p>
<H2><a name="Typemaps_nn48">13.14 More about %apply and %clear</a></H2>
<H2><a name="Typemaps_nn48">14.14 More about %apply and %clear</a></H2>
<p>
@ -5054,7 +5054,7 @@ will delete the typemaps for all the typemap methods; namely "in", "check" and "
</pre>
</div>
<H2><a name="Typemaps_nn47">13.15 Passing data between typemaps</a></H2>
<H2><a name="Typemaps_nn47">14.15 Passing data between typemaps</a></H2>
<p>
@ -5091,7 +5091,7 @@ sure that the typemaps sharing information have exactly the same types and names
</p>
<H2><a name="Typemaps_nn52">13.16 C++ "this" pointer</a></H2>
<H2><a name="Typemaps_nn52">14.16 C++ "this" pointer</a></H2>
<p>
@ -5151,7 +5151,7 @@ will also match the typemap. One work around is to create an interface file tha
the method, but gives the argument a name other than <tt>self</tt>.
</p>
<H2><a name="Typemaps_nn51">13.17 Where to go for more information?</a></H2>
<H2><a name="Typemaps_nn51">14.17 Where to go for more information?</a></H2>
<p>