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

Add C++20 documentation chapter

Browse source
This commit is contained in:
William S Fulton 2020-06-08 20:52:57 +01:00
commit b7bcb338cf
36 changed files with 1088 additions and 1030 deletions
Download patch file Download diff file Expand all files Collapse all files

200
Doc/Manual/Ruby.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Ruby">34 SWIG and Ruby</a></H1>
<H1><a name="Ruby">35 SWIG and Ruby</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -149,7 +149,7 @@
<p>This chapter describes SWIG's support of Ruby.</p>
<H2><a name="Ruby_nn2">34.1 Preliminaries</a></H2>
<H2><a name="Ruby_nn2">35.1 Preliminaries</a></H2>
<p> SWIG 4.0 is known to work with Ruby versions 1.9 and later.
@ -164,7 +164,7 @@ read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter. It is also assumed that the reader has a basic understanding
of Ruby. </p>
<H3><a name="Ruby_nn3">34.1.1 Running SWIG</a></H3>
<H3><a name="Ruby_nn3">35.1.1 Running SWIG</a></H3>
<p> To build a Ruby module, run SWIG using the <tt>-ruby</tt>
@ -188,7 +188,7 @@ if compiling a C++ extension) that contains all of the code needed to
build a Ruby extension module. To finish building the module, you need
to compile this file and link it with the rest of your program. </p>
<H3><a name="Ruby_nn4">34.1.2 Getting the right header files</a></H3>
<H3><a name="Ruby_nn4">35.1.2 Getting the right header files</a></H3>
<p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
@ -202,7 +202,7 @@ the compiler options needed to compile the code is to ask Ruby itself:</p>
</pre>
</div>
<H3><a name="Ruby_nn5">34.1.3 Compiling a dynamic module</a></H3>
<H3><a name="Ruby_nn5">35.1.3 Compiling a dynamic module</a></H3>
<p> Ruby extension modules are typically compiled into shared
@ -275,7 +275,7 @@ manual pages for your compiler and linker to determine the correct set
of options. You might also check the <a href="https://github.com/swig/swig/wiki">SWIG Wiki</a>
for additional information. </p>
<H3><a name="Ruby_nn6">34.1.4 Using your module</a></H3>
<H3><a name="Ruby_nn6">35.1.4 Using your module</a></H3>
<p> Ruby <i>module</i> names must be capitalized,
@ -305,7 +305,7 @@ begins with: </p>
<p> will result in an extension module using the feature name
"example" and Ruby module name "Example". </p>
<H3><a name="Ruby_nn7">34.1.5 Static linking</a></H3>
<H3><a name="Ruby_nn7">35.1.5 Static linking</a></H3>
<p> An alternative approach to dynamic linking is to rebuild the
@ -320,7 +320,7 @@ finding the Ruby source, adding an entry to the <tt>ext/Setup</tt>
file, adding your directory to the list of extensions in the file, and
finally rebuilding Ruby. </p>
<H3><a name="Ruby_nn8">34.1.6 Compilation of C++ extensions</a></H3>
<H3><a name="Ruby_nn8">35.1.6 Compilation of C++ extensions</a></H3>
<p> On most machines, C++ extension modules should be linked
@ -352,7 +352,7 @@ $libs = append_library($libs, "supc++")
create_makefile('example')</pre>
</div>
<H2><a name="Ruby_nn9">34.2 Building Ruby Extensions under Windows 95/NT</a></H2>
<H2><a name="Ruby_nn9">35.2 Building Ruby Extensions under Windows 95/NT</a></H2>
<p> Building a SWIG extension to Ruby under Windows 95/NT is
@ -377,7 +377,7 @@ order to build extensions, you may need to download the source
distribution to the Ruby package, as you will need the Ruby header
files. </p>
<H3><a name="Ruby_nn10">34.2.1 Running SWIG from Developer Studio</a></H3>
<H3><a name="Ruby_nn10">35.2.1 Running SWIG from Developer Studio</a></H3>
<p> If you are developing your application within Microsoft
@ -441,13 +441,13 @@ Foo = 3.0
</pre>
</div>
<H2><a name="Ruby_nn11">34.3 The Ruby-to-C/C++ Mapping</a></H2>
<H2><a name="Ruby_nn11">35.3 The Ruby-to-C/C++ Mapping</a></H2>
<p> This section describes the basics of how SWIG maps C or C++
declarations in your SWIG interface files to Ruby constructs. </p>
<H3><a name="Ruby_nn12">34.3.1 Modules</a></H3>
<H3><a name="Ruby_nn12">35.3.1 Modules</a></H3>
<p> The SWIG <tt>%module</tt> directive specifies
@ -519,7 +519,7 @@ option to wrap everything into the global module, take care that the
names of your constants, classes and methods don't conflict with any of
Ruby's built-in names. </p>
<H3><a name="Ruby_nn13">34.3.2 Functions</a></H3>
<H3><a name="Ruby_nn13">35.3.2 Functions</a></H3>
<p> Global functions are wrapped as Ruby module methods. For
@ -553,7 +553,7 @@ irb(main):002:0&gt; <b>Example.fact(4)</b>
24</pre>
</div>
<H3><a name="Ruby_nn14">34.3.3 Variable Linking</a></H3>
<H3><a name="Ruby_nn14">35.3.3 Variable Linking</a></H3>
<p> C/C++ global variables are wrapped as a pair of singleton
@ -633,7 +633,7 @@ irb(main):004:0&gt; <b>$Variable2</b>
41.2</pre>
</div>
<H3><a name="Ruby_nn15">34.3.4 Constants</a></H3>
<H3><a name="Ruby_nn15">35.3.4 Constants</a></H3>
<p> C/C++ constants are wrapped as module constants initialized
@ -661,7 +661,7 @@ irb(main):002:0&gt; <b>Example::PI</b>
3.14159</pre>
</div>
<H3><a name="Ruby_nn16">34.3.5 Pointers</a></H3>
<H3><a name="Ruby_nn16">35.3.5 Pointers</a></H3>
<p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that
@ -685,7 +685,7 @@ returns an instance of an internally generated Ruby class: </p>
<p> A <tt>NULL</tt> pointer is always represented by
the Ruby <tt>nil</tt> object. </p>
<H3><a name="Ruby_nn17">34.3.6 Structures</a></H3>
<H3><a name="Ruby_nn17">35.3.6 Structures</a></H3>
<p> C/C++ structs are wrapped as Ruby classes, with accessor
@ -790,7 +790,7 @@ void Bar_f_set(Bar *b, Foo *val) {
}</pre>
</div>
<H3><a name="Ruby_nn18">34.3.7 C++ classes</a></H3>
<H3><a name="Ruby_nn18">35.3.7 C++ classes</a></H3>
<p> Like structs, C++ classes are wrapped by creating a new Ruby
@ -845,7 +845,7 @@ Ale
3</pre>
</div>
<H3><a name="Ruby_nn19">34.3.8 C++ Inheritance</a></H3>
<H3><a name="Ruby_nn19">35.3.8 C++ Inheritance</a></H3>
<p> The SWIG type-checker is fully aware of C++ inheritance.
@ -998,7 +998,7 @@ inherit from both <tt>Base1</tt> and <tt>Base2</tt>
(i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck
Typing"</a>). </p>
<H3><a name="Ruby_nn20">34.3.9 C++ Overloaded Functions</a></H3>
<H3><a name="Ruby_nn20">35.3.9 C++ Overloaded Functions</a></H3>
<p> C++ overloaded functions, methods, and constructors are
@ -1088,7 +1088,7 @@ arises--in this case, the first declaration takes precedence. </p>
<p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG
and C++"</a> chapter for more information about overloading. </p>
<H3><a name="Ruby_nn21">34.3.10 C++ Operators</a></H3>
<H3><a name="Ruby_nn21">35.3.10 C++ Operators</a></H3>
<p> For the most part, overloaded operators are handled
@ -1130,7 +1130,7 @@ c = Example.add_complex(a, b)</pre>
is discussed in the <a href="#Ruby_operator_overloading">section
on operator overloading</a>. </p>
<H3><a name="Ruby_nn22">34.3.11 C++ namespaces</a></H3>
<H3><a name="Ruby_nn22">35.3.11 C++ namespaces</a></H3>
<p> SWIG is aware of C++ namespaces, but namespace names do not
@ -1187,7 +1187,7 @@ and create extension modules for each namespace separately. If your
program utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve. </p>
<H3><a name="Ruby_nn23">34.3.12 C++ templates</a></H3>
<H3><a name="Ruby_nn23">35.3.12 C++ templates</a></H3>
<p> C++ templates don't present a huge problem for SWIG. However,
@ -1229,7 +1229,7 @@ irb(main):004:0&gt; <b>p.second</b>
4</pre>
</div>
<H3><a name="Ruby_nn23_1">34.3.13 C++ Standard Template Library (STL)</a></H3>
<H3><a name="Ruby_nn23_1">35.3.13 C++ Standard Template Library (STL)</a></H3>
<p> On a related note, the standard SWIG library contains a
@ -1322,7 +1322,7 @@ puts v
shown in these examples. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>
chapter.</p>
<H3><a name="Ruby_C_STL_Functors">34.3.14 C++ STL Functors</a></H3>
<H3><a name="Ruby_C_STL_Functors">35.3.14 C++ STL Functors</a></H3>
<p>Some containers in the STL allow you to modify their default
@ -1383,7 +1383,7 @@ b
</pre>
</div>
<H3><a name="Ruby_C_Iterators">34.3.15 C++ STL Iterators</a></H3>
<H3><a name="Ruby_C_Iterators">35.3.15 C++ STL Iterators</a></H3>
<p>The STL is well known for the use of iterators. There
@ -1466,10 +1466,10 @@ i
<p>If you'd rather have STL classes without any iterators, you should define <tt>-DSWIG_NO_EXPORT_ITERATOR_METHODS</tt> when running swig.</p>
<H3><a name="Ruby_nn24">34.3.16 C++ Smart Pointers</a></H3>
<H3><a name="Ruby_nn24">35.3.16 C++ Smart Pointers</a></H3>
<H4><a name="Ruby_smart_pointers_shared_ptr">34.3.16.1 The shared_ptr Smart Pointer</a></H4>
<H4><a name="Ruby_smart_pointers_shared_ptr">35.3.16.1 The shared_ptr Smart Pointer</a></H4>
<p>
@ -1480,7 +1480,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
</p>
<H4><a name="Ruby_smart_pointers_generic">34.3.16.2 Generic Smart Pointers</a></H4>
<H4><a name="Ruby_smart_pointers_generic">35.3.16.2 Generic Smart Pointers</a></H4>
<p> In certain C++ programs, it is common to use classes that
@ -1545,7 +1545,7 @@ method. For example: </p>
<pre>irb(main):004:0&gt; <b>f = p.__deref__()</b> # Returns underlying Foo *</pre>
</div>
<H3><a name="Ruby_nn25">34.3.17 Cross-Language Polymorphism</a></H3>
<H3><a name="Ruby_nn25">35.3.17 Cross-Language Polymorphism</a></H3>
<p> SWIG's Ruby module supports cross-language polymorphism
@ -1554,7 +1554,7 @@ module. Rather than duplicate the information presented in the <a href="Python.h
section just notes the differences that you need to be aware of when
using this feature with Ruby. </p>
<H4><a name="Ruby_nn26">34.3.17.1 Exception Unrolling</a></H4>
<H4><a name="Ruby_nn26">35.3.17.1 Exception Unrolling</a></H4>
<p> Whenever a C++ director class routes one of its virtual
@ -1577,7 +1577,7 @@ method is "wrapped" using the <tt>rb_rescue2()</tt>
function from Ruby's C API. If any Ruby exception is raised, it will be
caught here and a C++ exception is raised in its place. </p>
<H2><a name="Ruby_nn27">34.4 Naming</a></H2>
<H2><a name="Ruby_nn27">35.4 Naming</a></H2>
<p>Ruby has several common naming conventions. Constants are
@ -1615,7 +1615,7 @@ generated
by SWIG, it is turned off by default in SWIG 1.3.28. However, it is
planned to become the default option in future releases.</p>
<H3><a name="Ruby_nn28">34.4.1 Defining Aliases</a></H3>
<H3><a name="Ruby_nn28">35.4.1 Defining Aliases</a></H3>
<p> It's a fairly common practice in the Ruby built-ins and
@ -1685,7 +1685,7 @@ matching rules used for other kinds of features apply (see the chapter
on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details).</p>
<H3><a name="Ruby_nn29">34.4.2 Predicate Methods</a></H3>
<H3><a name="Ruby_nn29">35.4.2 Predicate Methods</a></H3>
<p> Ruby methods that return a boolean value and end in a
@ -1734,7 +1734,7 @@ using SWIG's "features" mechanism and so the same name matching rules
used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details). </p>
<H3><a name="Ruby_nn30">34.4.3 Bang Methods</a></H3>
<H3><a name="Ruby_nn30">35.4.3 Bang Methods</a></H3>
<p> Ruby methods that modify an object in-place and end in an
@ -1766,7 +1766,7 @@ using SWIG's "features" mechanism and so the same name matching rules
used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details). </p>
<H3><a name="Ruby_nn31">34.4.4 Getters and Setters</a></H3>
<H3><a name="Ruby_nn31">35.4.4 Getters and Setters</a></H3>
<p> Often times a C++ library will expose properties through
@ -1801,7 +1801,7 @@ irb(main):003:0&gt; <b>puts foo.value</b></pre>
%rename("value=") Foo::setValue(int value);</pre>
</div>
<H2><a name="Ruby_nn32">34.5 Input and output parameters</a></H2>
<H2><a name="Ruby_nn32">35.5 Input and output parameters</a></H2>
<p> A common problem in some C programs is handling parameters
@ -1940,10 +1940,10 @@ void get_dimensions(Matrix *m, int *rows, int*columns);</pre>
<pre>r, c = Example.get_dimensions(m)</pre>
</div>
<H2><a name="Ruby_nn33">34.6 Exception handling </a></H2>
<H2><a name="Ruby_nn33">35.6 Exception handling </a></H2>
<H3><a name="Ruby_nn34">34.6.1 Using the %exception directive </a></H3>
<H3><a name="Ruby_nn34">35.6.1 Using the %exception directive </a></H3>
<p>The SWIG <tt>%exception</tt> directive can be
@ -2052,7 +2052,7 @@ methods and functions named <tt>getitem</tt> and <tt>setitem</tt>.
limited to C++ exception handling. See the chapter on <a href="Customization.html#Customization">Customization
Features</a> for more examples.</p>
<H3><a name="Ruby_nn34_2">34.6.2 Handling Ruby Blocks </a></H3>
<H3><a name="Ruby_nn34_2">35.6.2 Handling Ruby Blocks </a></H3>
<p>One of the highlights of Ruby and most of its standard library
@ -2119,7 +2119,7 @@ a special in typemap, like:</p>
<p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p>
<H3><a name="Ruby_nn35">34.6.3 Raising exceptions </a></H3>
<H3><a name="Ruby_nn35">35.6.3 Raising exceptions </a></H3>
<p>There are three ways to raise exceptions from C++ code to
@ -2276,7 +2276,7 @@ function. The first argument passed to <tt>rb_raise()</tt>
is the exception type. You can raise a custom exception type or one of
the built-in Ruby exception types.</p>
<H3><a name="Ruby_nn36">34.6.4 Exception classes </a></H3>
<H3><a name="Ruby_nn36">35.6.4 Exception classes </a></H3>
<p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt>
@ -2313,7 +2313,7 @@ end </pre>
<p>For another example look at swig/Examples/ruby/exception_class.
</p>
<H2><a name="Ruby_nn37">34.7 Typemaps</a></H2>
<H2><a name="Ruby_nn37">35.7 Typemaps</a></H2>
<p> This section describes how you can modify SWIG's default
@ -2328,7 +2328,7 @@ a required part of using SWIG---the default wrapping behavior is enough
in most cases. Typemaps are only used if you want to change some aspect
of the primitive C-Ruby interface.</p>
<H3><a name="Ruby_nn38">34.7.1 What is a typemap?</a></H3>
<H3><a name="Ruby_nn38">35.7.1 What is a typemap?</a></H3>
<p> A typemap is nothing more than a code generation rule that is
@ -2485,7 +2485,7 @@ to be used as follows (notice how the length parameter is omitted): </p>
2</pre>
</div>
<H3><a name="Ruby_Typemap_scope">34.7.2 Typemap scope</a></H3>
<H3><a name="Ruby_Typemap_scope">35.7.2 Typemap scope</a></H3>
<p> Once defined, a typemap remains in effect for all of the
@ -2531,7 +2531,7 @@ where the class itself is defined. For example:</p>
};</pre>
</div>
<H3><a name="Ruby_Copying_a_typemap">34.7.3 Copying a typemap</a></H3>
<H3><a name="Ruby_Copying_a_typemap">35.7.3 Copying a typemap</a></H3>
<p> A typemap is copied by using assignment. For example:</p>
@ -2573,7 +2573,7 @@ rules as for <tt>
%apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments</pre>
</div>
<H3><a name="Ruby_Deleting_a_typemap">34.7.4 Deleting a typemap</a></H3>
<H3><a name="Ruby_Deleting_a_typemap">35.7.4 Deleting a typemap</a></H3>
<p> A typemap can be deleted by simply defining no code. For
@ -2598,7 +2598,7 @@ defined by typemaps, clearing a fundamental type like <tt>int</tt>
will make that type unusable unless you also define a new set of
typemaps immediately after the clear operation.</p>
<H3><a name="Ruby_Placement_of_typemaps">34.7.5 Placement of typemaps</a></H3>
<H3><a name="Ruby_Placement_of_typemaps">35.7.5 Placement of typemaps</a></H3>
<p> Typemap declarations can be declared in the global scope,
@ -2669,13 +2669,13 @@ In this example, this is done using the class declaration <tt>class
string</tt>
.</p>
<H3><a name="Ruby_nn39">34.7.6 Ruby typemaps</a></H3>
<H3><a name="Ruby_nn39">35.7.6 Ruby typemaps</a></H3>
<p>The following list details all of the typemap methods that
can be used by the Ruby module: </p>
<H4><a name="Ruby_in_typemap">34.7.6.1 "in" typemap</a></H4>
<H4><a name="Ruby_in_typemap">35.7.6.1 "in" typemap</a></H4>
<p>Converts Ruby objects to input
@ -2742,7 +2742,7 @@ arguments to be specified. For example:</p>
<p> At this time, only zero or one arguments may be converted.</p>
<H4><a name="Ruby_typecheck_typemap">34.7.6.2 "typecheck" typemap</a></H4>
<H4><a name="Ruby_typecheck_typemap">35.7.6.2 "typecheck" typemap</a></H4>
<p> The "typecheck" typemap is used to support overloaded
@ -2764,7 +2764,7 @@ program uses overloaded methods, you should also define a collection of
"typecheck" typemaps. More details about this follow in a later section
on "Typemaps and Overloading."</p>
<H4><a name="Ruby_out_typemap">34.7.6.3 "out" typemap</a></H4>
<H4><a name="Ruby_out_typemap">35.7.6.3 "out" typemap</a></H4>
<p>Converts return value of a C function
@ -2815,7 +2815,7 @@ version of the C datatype matched by the typemap.</td>
</table>
</div>
<H4><a name="Ruby_arginit_typemap">34.7.6.4 "arginit" typemap</a></H4>
<H4><a name="Ruby_arginit_typemap">35.7.6.4 "arginit" typemap</a></H4>
<p> The "arginit" typemap is used to set the initial value of a
@ -2830,7 +2830,7 @@ applications. For example:</p>
}</pre>
</div>
<H4><a name="Ruby_default_typemap">34.7.6.5 "default" typemap</a></H4>
<H4><a name="Ruby_default_typemap">35.7.6.5 "default" typemap</a></H4>
<p> The "default" typemap is used to turn an argument into a
@ -2855,7 +2855,7 @@ arguments that follow must have default values. See the <a href="SWIG.html#SWIG_
Default/optional arguments</a> section for further information on
default argument wrapping.</p>
<H4><a name="Ruby_check_typemap">34.7.6.6 "check" typemap</a></H4>
<H4><a name="Ruby_check_typemap">35.7.6.6 "check" typemap</a></H4>
<p> The "check" typemap is used to supply value checking code
@ -2870,7 +2870,7 @@ arguments have been converted. For example:</p>
}</pre>
</div>
<H4><a name="Ruby_argout_typemap_">34.7.6.7 "argout" typemap</a></H4>
<H4><a name="Ruby_argout_typemap_">35.7.6.7 "argout" typemap</a></H4>
<p> The "argout" typemap is used to return values from arguments.
@ -2924,7 +2924,7 @@ some function like SWIG_Ruby_AppendOutput.</p>
<p> See the <tt>typemaps.i</tt> library for examples.</p>
<H4><a name="Ruby_freearg_typemap_">34.7.6.8 "freearg" typemap</a></H4>
<H4><a name="Ruby_freearg_typemap_">35.7.6.8 "freearg" typemap</a></H4>
<p> The "freearg" typemap is used to cleanup argument data. It is
@ -2951,7 +2951,7 @@ This code is also placed into a special variable <tt>$cleanup</tt>
that may be used in other typemaps whenever a wrapper function needs to
abort prematurely.</p>
<H4><a name="Ruby_newfree_typemap">34.7.6.9 "newfree" typemap</a></H4>
<H4><a name="Ruby_newfree_typemap">35.7.6.9 "newfree" typemap</a></H4>
<p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt>
@ -2975,7 +2975,7 @@ string *foo();</pre>
<p> See <a href="Customization.html#Customization_ownership">Object
ownership and %newobject</a> for further details.</p>
<H4><a name="Ruby_memberin_typemap">34.7.6.10 "memberin" typemap</a></H4>
<H4><a name="Ruby_memberin_typemap">35.7.6.10 "memberin" typemap</a></H4>
<p> The "memberin" typemap is used to copy data from<em> an
@ -2993,21 +2993,21 @@ example:</p>
already provides a default implementation for arrays, strings, and
other objects.</p>
<H4><a name="Ruby_varin_typemap">34.7.6.11 "varin" typemap</a></H4>
<H4><a name="Ruby_varin_typemap">35.7.6.11 "varin" typemap</a></H4>
<p> The "varin" typemap is used to convert objects in the target
language to C for the purposes of assigning to a C/C++ global variable.
This is implementation specific.</p>
<H4><a name="Ruby_varout_typemap_">34.7.6.12 "varout" typemap</a></H4>
<H4><a name="Ruby_varout_typemap_">35.7.6.12 "varout" typemap</a></H4>
<p> The "varout" typemap is used to convert a C/C++ object to an
object in the target language when reading a C/C++ global variable.
This is implementation specific.</p>
<H4><a name="Ruby_throws_typemap">34.7.6.13 "throws" typemap</a></H4>
<H4><a name="Ruby_throws_typemap">35.7.6.13 "throws" typemap</a></H4>
<p> The "throws" typemap is only used when SWIG parses a C++
@ -3048,7 +3048,7 @@ specification yet they do throw exceptions, SWIG cannot know how to
deal with them. For a neat way to handle these, see the <a href="Customization.html#Customization_exception">Exception
handling with %exception</a> section.</p>
<H4><a name="Ruby_directorin_typemap">34.7.6.14 directorin typemap</a></H4>
<H4><a name="Ruby_directorin_typemap">35.7.6.14 directorin typemap</a></H4>
<p>Converts C++ objects in director
@ -3107,7 +3107,7 @@ referring to the class itself.</td>
</table>
</div>
<H4><a name="Ruby_directorout_typemap">34.7.6.15 directorout typemap</a></H4>
<H4><a name="Ruby_directorout_typemap">35.7.6.15 directorout typemap</a></H4>
<p>Converts Ruby objects in director
@ -3180,7 +3180,7 @@ exception.
</p>
<H4><a name="Ruby_directorargout_typemap">34.7.6.16 directorargout typemap</a></H4>
<H4><a name="Ruby_directorargout_typemap">35.7.6.16 directorargout typemap</a></H4>
<p>Output argument processing in director
@ -3238,19 +3238,19 @@ referring to the instance of the class itself</td>
</table>
</div>
<H4><a name="Ruby_ret_typemap">34.7.6.17 ret typemap</a></H4>
<H4><a name="Ruby_ret_typemap">35.7.6.17 ret typemap</a></H4>
<p>Cleanup of function return values
</p>
<H4><a name="Ruby_globalin_typemap">34.7.6.18 globalin typemap</a></H4>
<H4><a name="Ruby_globalin_typemap">35.7.6.18 globalin typemap</a></H4>
<p>Setting of C global variables
</p>
<H3><a name="Ruby_nn40">34.7.7 Typemap variables</a></H3>
<H3><a name="Ruby_nn40">35.7.7 Typemap variables</a></H3>
<p>
@ -3300,7 +3300,7 @@ so that their values can be properly assigned. </div>
<div class="indent">The Ruby name of the wrapper function
being created. </div>
<H3><a name="Ruby_nn41">34.7.8 Useful Functions</a></H3>
<H3><a name="Ruby_nn41">35.7.8 Useful Functions</a></H3>
<p> When you write a typemap, you usually have to work directly
@ -3315,7 +3315,7 @@ stick to the swig functions instead of the native Ruby functions.
That should help you avoid having to rewrite a lot of typemaps
across multiple languages.</p>
<H4><a name="Ruby_nn42">34.7.8.1 C Datatypes to Ruby Objects</a></H4>
<H4><a name="Ruby_nn42">35.7.8.1 C Datatypes to Ruby Objects</a></H4>
<div class="diagram">
@ -3357,7 +3357,7 @@ SWIG_From_float(float)</td>
</table>
</div>
<H4><a name="Ruby_nn43">34.7.8.2 Ruby Objects to C Datatypes</a></H4>
<H4><a name="Ruby_nn43">35.7.8.2 Ruby Objects to C Datatypes</a></H4>
<p>Here, while the Ruby versions return the value directly, the SWIG
@ -3425,7 +3425,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
</table>
</div>
<H4><a name="Ruby_nn44">34.7.8.3 Macros for VALUE</a></H4>
<H4><a name="Ruby_nn44">35.7.8.3 Macros for VALUE</a></H4>
<p> <tt>RSTRING_LEN(str)</tt> </p>
@ -3448,7 +3448,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
<div class="indent">pointer to array storage</div>
<H4><a name="Ruby_nn45">34.7.8.4 Exceptions</a></H4>
<H4><a name="Ruby_nn45">35.7.8.4 Exceptions</a></H4>
<p> <tt>void rb_raise(VALUE exception, const char *fmt,
@ -3527,7 +3527,7 @@ message to standard error if Ruby was invoked with the <tt>-w</tt>
flag. The given format string <i>fmt</i> and remaining
arguments are interpreted as with <tt>printf()</tt>. </div>
<H4><a name="Ruby_nn46">34.7.8.5 Iterators</a></H4>
<H4><a name="Ruby_nn46">35.7.8.5 Iterators</a></H4>
<p> <tt>void rb_iter_break()</tt> </p>
@ -3573,14 +3573,14 @@ VALUE), VALUE value)</tt></p>
<div class="indent"> Equivalent to Ruby's <tt>throw</tt>.
</div>
<H3><a name="Ruby_nn47">34.7.9 Typemap Examples</a></H3>
<H3><a name="Ruby_nn47">35.7.9 Typemap Examples</a></H3>
<p> This section includes a few examples of typemaps. For more
examples, you might look at the examples in the <tt>Example/ruby</tt>
directory. </p>
<H3><a name="Ruby_nn48">34.7.10 Converting a Ruby array to a char **</a></H3>
<H3><a name="Ruby_nn48">35.7.10 Converting a Ruby array to a char **</a></H3>
<p> A common problem in many C programs is the processing of
@ -3645,7 +3645,7 @@ array. Since dynamic memory allocation is used to allocate memory for
the array, the "freearg" typemap is used to later release this memory
after the execution of the C function. </p>
<H3><a name="Ruby_nn49">34.7.11 Collecting arguments in a hash</a></H3>
<H3><a name="Ruby_nn49">35.7.11 Collecting arguments in a hash</a></H3>
<p> Ruby's solution to the "keyword arguments" capability of some
@ -3859,7 +3859,7 @@ memory leak. Fortunately, this typemap is a lot easier to write: </p>
program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
directory of the SWIG distribution. </p>
<H3><a name="Ruby_nn50">34.7.12 Pointer handling</a></H3>
<H3><a name="Ruby_nn50">35.7.12 Pointer handling</a></H3>
<p> Occasionally, it might be necessary to convert pointer values
@ -3918,7 +3918,7 @@ For example: </p>
}</pre>
</div>
<H4><a name="Ruby_nn51">34.7.12.1 Ruby Datatype Wrapping</a></H4>
<H4><a name="Ruby_nn51">35.7.12.1 Ruby Datatype Wrapping</a></H4>
<p> <tt>VALUE Data_Wrap_Struct(VALUE class, void
@ -3945,7 +3945,7 @@ as above. </div>
type <i>c-type</i> from the data object <i>obj</i>
and assigns that pointer to <i>ptr</i>. </div>
<H3><a name="Ruby_nn52">34.7.13 Example: STL Vector to Ruby Array</a></H3>
<H3><a name="Ruby_nn52">35.7.13 Example: STL Vector to Ruby Array</a></H3>
<p>Another use for macros and type maps is to create a Ruby array
@ -4037,7 +4037,7 @@ STL with ruby, you are advised to use the standard swig STL library,
which does much more than this. Refer to the section called
the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.
<H2><a name="Ruby_nn65">34.8 Docstring Features</a></H2>
<H2><a name="Ruby_nn65">35.8 Docstring Features</a></H2>
<p>
@ -4071,7 +4071,7 @@ generate ri documentation from a c wrap file, you could do:</p>
$ rdoc -r file_wrap.c
</pre></div>
<H3><a name="Ruby_nn66">34.8.1 Module docstring</a></H3>
<H3><a name="Ruby_nn66">35.8.1 Module docstring</a></H3>
<p>
@ -4101,7 +4101,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
%module(docstring=DOCSTRING) xrc</pre>
</div>
<H3><a name="Ruby_nn67">34.8.2 %feature("autodoc")</a></H3>
<H3><a name="Ruby_nn67">35.8.2 %feature("autodoc")</a></H3>
<p>Since SWIG does know everything about the function it wraps,
@ -4122,7 +4122,7 @@ several options for autodoc controlled by the value given to the
feature, described below.
</p>
<H4><a name="Ruby_nn68">34.8.2.1 %feature("autodoc", "0")</a></H4>
<H4><a name="Ruby_nn68">35.8.2.1 %feature("autodoc", "0")</a></H4>
<p>
@ -4146,7 +4146,7 @@ Then Ruby code like this will be generated:
...</pre>
</div>
<H4><a name="Ruby_autodoc1">34.8.2.2 %feature("autodoc", "1")</a></H4>
<H4><a name="Ruby_autodoc1">35.8.2.2 %feature("autodoc", "1")</a></H4>
<p>
@ -4166,7 +4166,7 @@ this:
...</pre>
</div>
<H4><a name="Ruby_autodoc2">34.8.2.3 %feature("autodoc", "2")</a></H4>
<H4><a name="Ruby_autodoc2">35.8.2.3 %feature("autodoc", "2")</a></H4>
<p>
@ -4178,7 +4178,7 @@ parameter types with the "2" option will result in Ruby code like
this:
</p>
<H4><a name="Ruby_feature_autodoc3">34.8.2.4 %feature("autodoc", "3")</a></H4>
<H4><a name="Ruby_feature_autodoc3">35.8.2.4 %feature("autodoc", "3")</a></H4>
<p>
@ -4199,7 +4199,7 @@ Parameters:
bar - Bar</pre>
</div>
<H4><a name="Ruby_nn70">34.8.2.5 %feature("autodoc", "docstring")</a></H4>
<H4><a name="Ruby_nn70">35.8.2.5 %feature("autodoc", "docstring")</a></H4>
<p>
@ -4215,7 +4215,7 @@ generated string. For example:
void GetPosition(int* OUTPUT, int* OUTPUT);</pre>
</div>
<H3><a name="Ruby_nn71">34.8.3 %feature("docstring")</a></H3>
<H3><a name="Ruby_nn71">35.8.3 %feature("docstring")</a></H3>
<p>
@ -4226,10 +4226,10 @@ docstring associated with classes, function or methods are output.
If an item already has an autodoc string then it is combined with the
docstring and they are output together. </p>
<H2><a name="Ruby_nn53">34.9 Advanced Topics</a></H2>
<H2><a name="Ruby_nn53">35.9 Advanced Topics</a></H2>
<H3><a name="Ruby_operator_overloading">34.9.1 Operator overloading</a></H3>
<H3><a name="Ruby_operator_overloading">35.9.1 Operator overloading</a></H3>
<p> SWIG allows operator overloading with, by using the <tt>%extend</tt>
@ -4410,7 +4410,7 @@ separate method for handling <i>inequality</i> since Ruby
parses the expression <i>a != b</i> as <i>!(a == b)</i>.
</p>
<H3><a name="Ruby_nn55">34.9.2 Creating Multi-Module Packages</a></H3>
<H3><a name="Ruby_nn55">35.9.2 Creating Multi-Module Packages</a></H3>
<p> The chapter on <a href="Modules.html#Modules">Working
@ -4536,7 +4536,7 @@ irb(main):005:0&gt; <b>c.getX()</b>
5.0</pre>
</div>
<H3><a name="Ruby_nn56">34.9.3 Specifying Mixin Modules</a></H3>
<H3><a name="Ruby_nn56">35.9.3 Specifying Mixin Modules</a></H3>
<p> The Ruby language doesn't support multiple inheritance, but
@ -4603,7 +4603,7 @@ matching rules used for other kinds of features apply (see the chapter
on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details). </p>
<H2><a name="Ruby_nn57">34.10 Memory Management</a></H2>
<H2><a name="Ruby_nn57">35.10 Memory Management</a></H2>
<p>One of the most common issues in generating SWIG bindings for
@ -4626,7 +4626,7 @@ to C++ (or vice versa) depending on what function or methods are
invoked. Clearly, developing a SWIG wrapper requires a thorough
understanding of how the underlying library manages memory.</p>
<H3><a name="Ruby_nn58">34.10.1 Mark and Sweep Garbage Collector </a></H3>
<H3><a name="Ruby_nn58">35.10.1 Mark and Sweep Garbage Collector </a></H3>
<p>Ruby uses a mark and sweep garbage collector. When the garbage
@ -4657,7 +4657,7 @@ any memory has been allocated in creating the underlying C struct or
C++ struct, then a "free" function must be defined that deallocates
this memory. </p>
<H3><a name="Ruby_nn59">34.10.2 Object Ownership</a></H3>
<H3><a name="Ruby_nn59">35.10.2 Object Ownership</a></H3>
<p>As described above, memory management depends on clearly
@ -4802,7 +4802,7 @@ public:
<p> This code can be seen in swig/examples/ruby/tracking.</p>
<H3><a name="Ruby_nn60">34.10.3 Object Tracking</a></H3>
<H3><a name="Ruby_nn60">35.10.3 Object Tracking</a></H3>
<p>The remaining parts of this section will use the class library
@ -5028,7 +5028,7 @@ However, if you implement your own free functions (see below) you may
also have to call the <tt>SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt>
methods.</p>
<H3><a name="Ruby_nn61">34.10.4 Mark Functions</a></H3>
<H3><a name="Ruby_nn61">35.10.4 Mark Functions</a></H3>
<p>With a bit more testing, we see that our class library still
@ -5157,7 +5157,7 @@ irb(main):016:0&gt;</pre>
<p>This code can be seen in swig/examples/ruby/mark_function.</p>
<H3><a name="Ruby_nn62">34.10.5 Free Functions</a></H3>
<H3><a name="Ruby_nn62">35.10.5 Free Functions</a></H3>
<p>By default, SWIG creates a "free" function that is called when
@ -5325,7 +5325,7 @@ been freed, and thus raises a runtime exception.</p>
<p>This code can be seen in swig/examples/ruby/free_function.</p>
<H3><a name="Ruby_nn63">34.10.6 Embedded Ruby and the C++ Stack</a></H3>
<H3><a name="Ruby_nn63">35.10.6 Embedded Ruby and the C++ Stack</a></H3>
<p>As has been said, the Ruby GC runs and marks objects before