changes after maketoc.py was run

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@6039 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2004-07-12 19:59:40 +00:00
commit 07b2b75836
22 changed files with 436 additions and 362 deletions

View file

@ -5,132 +5,87 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<h1>23 SWIG and Ruby</h1>
<a name="n1"></a><H1>23 SWIG and Ruby</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Preliminaries</a>
<ul>
<li><a href="#n3">Running SWIG</a>
</li>
<li><a href="#n4">Getting the right header files</a>
</li>
<li><a href="#n5">Compiling a dynamic module</a>
</li>
<li><a href="#n6">Using your module</a>
</li>
<li><a href="#n7">Static linking</a>
</li>
<li><a href="#n8">Compilation of C++ extensions</a>
</li>
</ul>
</li>
<li><a href="#n9">Building Ruby Extensions under Windows 95/NT</a>
<ul>
<li><a href="#n10">Running SWIG from Developer Studio</a>
</li>
</ul>
</li>
<li><a href="#n11">The Ruby-to-C/C++ Mapping</a>
<ul>
<li><a href="#n12">Modules</a>
</li>
<li><a href="#n13">Functions</a>
</li>
<li><a href="#n14">Variable Linking</a>
</li>
<li><a href="#n15">Constants</a>
</li>
<li><a href="#n16">Pointers</a>
</li>
<li><a href="#n17">Structures</a>
</li>
<li><a href="#n18">C++ classes</a>
</li>
<li><a href="#n19">C++ Inheritance</a>
</li>
<li><a href="#n20">C++ Overloaded Functions</a>
</li>
<li><a href="#n21">C++ Operators</a>
</li>
<li><a href="#n22">C++ namespaces</a>
</li>
<li><a href="#n23">C++ templates</a>
</li>
<li><a href="#n24">C++ Smart Pointers</a>
</li>
<li><a href="#n25">Cross-Language Polymorphism</a>
<ul>
<li><a href="#n26">Exception Unrolling</a>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="#n27">Input and output parameters</a>
</li>
<li><a href="#n28">Simple exception handling </a>
</li>
<li><a href="#n29">Typemaps</a>
<ul>
<li><a href="#n30">What is a typemap?</a>
</li>
<li><a href="#n31">Ruby typemaps</a>
</li>
<li><a href="#n32">Typemap variables</a>
</li>
<li><a href="#n33">Useful Functions</a>
<ul>
<li><a href="#n34">C Datatypes to Ruby Objects</a>
</li>
<li><a href="#n35">Ruby Objects to C Datatypes</a>
</li>
<li><a href="#n36">Macros for VALUE</a>
</li>
<li><a href="#n37">Exceptions</a>
</li>
<li><a href="#n38">Iterators</a>
</li>
</ul>
</li>
<li><a href="#n39">Typemap Examples</a>
</li>
<li><a href="#n40">Converting a Ruby array to a char **</a>
</li>
<li><a href="#n41">Collecting arguments in a hash</a>
</li>
<li><a href="#n42">Pointer handling</a>
<ul>
<li><a href="#n43">Ruby Datatype Wrapping</a>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="#n44">Operator overloading</a>
<ul>
<li><a href="#n45">Example: STL Vector to Ruby Array</a>
</li>
</ul>
</li>
<li><a href="#n46">Advanced Topics</a>
<ul>
<li><a href="#n47">Creating Multi-Module Packages</a>
</li>
<li><a href="#n48">Defining Aliases</a>
</li>
<li><a href="#n49">Predicate Methods</a>
</li>
<li><a href="#n50">Specifying Mixin Modules</a>
</li>
<li><a href="#n51">Interacting with Ruby's Garbage Collector</a>
</li>
</ul>
</li>
<li><a href="#n2">Preliminaries</a>
<ul>
<li><a href="#n3">Running SWIG</a>
<li><a href="#n4">Getting the right header files</a>
<li><a href="#n5">Compiling a dynamic module</a>
<li><a href="#n6">Using your module</a>
<li><a href="#n7">Static linking</a>
<li><a href="#n8">Compilation of C++ extensions</a>
</ul>
<li><a href="#n9">Building Ruby Extensions under Windows 95/NT</a>
<ul>
<li><a href="#n10">Running SWIG from Developer Studio</a>
</ul>
<li><a href="#n11">The Ruby-to-C/C++ Mapping</a>
<ul>
<li><a href="#n12">Modules</a>
<li><a href="#n13">Functions</a>
<li><a href="#n14">Variable Linking</a>
<li><a href="#n15">Constants</a>
<li><a href="#n16">Pointers</a>
<li><a href="#n17">Structures</a>
<li><a href="#n18">C++ classes</a>
<li><a href="#n19">C++ Inheritance</a>
<li><a href="#n20">C++ Overloaded Functions</a>
<li><a href="#n21">C++ Operators</a>
<li><a href="#n22">C++ namespaces</a>
<li><a href="#n23">C++ templates</a>
<li><a href="#n24">C++ Smart Pointers</a>
<li><a href="#n25">Cross-Language Polymorphism</a>
<ul>
<li><a href="#n26">Exception Unrolling</a>
</ul>
</ul>
<li><a href="#n27">Input and output parameters</a>
<li><a href="#n28">Simple exception handling </a>
<li><a href="#n29">Typemaps</a>
<ul>
<li><a href="#n30">What is a typemap?</a>
<li><a href="#n31">Ruby typemaps</a>
<li><a href="#n32">Typemap variables</a>
<li><a href="#n33">Useful Functions</a>
<ul>
<li><a href="#n34">C Datatypes to Ruby Objects</a>
<li><a href="#n35">Ruby Objects to C Datatypes</a>
<li><a href="#n36">Macros for VALUE</a>
<li><a href="#n37">Exceptions</a>
<li><a href="#n38">Iterators</a>
</ul>
<li><a href="#n39">Typemap Examples</a>
<li><a href="#n40">Converting a Ruby array to a char **</a>
<li><a href="#n41">Collecting arguments in a hash</a>
<li><a href="#n42">Pointer handling</a>
<ul>
<li><a href="#n43">Ruby Datatype Wrapping</a>
</ul>
</ul>
<li><a href="#n44">Operator overloading</a>
<ul>
<li><a href="#n45">Example: STL Vector to Ruby Array</a>
</ul>
<li><a href="#n46">Advanced Topics</a>
<ul>
<li><a href="#n47">Creating Multi-Module Packages</a>
<li><a href="#n48">Defining Aliases</a>
<li><a href="#n49">Predicate Methods</a>
<li><a href="#n50">Specifying Mixin Modules</a>
<li><a href="#n51">Interacting with Ruby's Garbage Collector</a>
</ul>
</ul>
<!-- INDEX -->
<p>This chapter describes SWIG's support of Ruby. </p>
<hr><a name="n2"></a>
<h2>23.1 Preliminaries</h2>
<a name="n2"></a><H2>23.1 Preliminaries</H2>
SWIG 1.3 is known to work with Ruby versions 1.6 and later. Given the
choice, you should
use the latest stable version of Ruby. You should also determine if
@ -145,7 +100,9 @@ earlier chapters. At the very least, make sure you also read the "<a
reader
has a basic understanding of Ruby.
<a name="n3"></a></p>
<h3>23.1.1 Running SWIG</h3>
<a name="n3"></a><H3>23.1.1 Running SWIG</H3>
<p>
To build a Ruby module, run SWIG using the <tt>-ruby</tt> option:</p>
<p></p>
@ -169,7 +126,9 @@ Ruby extension module. To finish building the module, you need to
compile this
file and link it with the rest of your program.
<a name="n4"></a></p>
<h3>23.1.2 Getting the right header files</h3>
<a name="n4"></a><H3>23.1.2 Getting the right header files</H3>
In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
header file. This file is usually contained in a directory such as
<p></p>
@ -191,7 +150,9 @@ can run Ruby to find out. For example:
</pre>
</blockquote>
<a name="n5"></a>
<h3>23.1.3 Compiling a dynamic module</h3>
<a name="n5"></a><H3>23.1.3 Compiling a dynamic module</H3>
Ruby extension modules are typically compiled into shared libraries
that the
interpreter loads dynamically at runtime. Since the exact commands for
@ -249,7 +210,9 @@ You might also check the <a
href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">
SWIG Wiki</a> for additional information.
<p> <a name="n6"></a></p>
<h3>23.1.4 Using your module</h3>
<a name="n6"></a><H3>23.1.4 Using your module</H3>
Ruby <i>module</i> names must be capitalized, but the convention for
Ruby
<i>feature</i> names is to use lowercase names. So, for example, the <b>Etc</b>
@ -263,7 +226,9 @@ extension. So for example, a SWIG interface file that begins with:
will result in an extension module using the feature name "example" and
Ruby module name "Example".
<a name="n7"></a>
<h3>23.1.5 Static linking</h3>
<a name="n7"></a><H3>23.1.5 Static linking</H3>
An alternative approach to dynamic linking is to rebuild the Ruby
interpreter with your extension module added to it. In the past,
this approach was sometimes necessary due to limitations in dynamic
@ -278,7 +243,9 @@ adding your directory to the list of extensions in the file, and
finally rebuilding Ruby.
</p>
<p><a name="n8"></a></p>
<h3>23.1.6 Compilation of C++ extensions</h3>
<a name="n8"></a><H3>23.1.6 Compilation of C++ extensions</H3>
<p>
On most machines, C++ extension modules should be linked using the C++
compiler. For example:
@ -310,7 +277,9 @@ into your extension, e.g.
</blockquote>
<hr>
<a name="n9"></a>
<h2>23.2 Building Ruby Extensions under Windows 95/NT</h2>
<a name="n9"></a><H2>23.2 Building Ruby Extensions under Windows 95/NT</H2>
Building a SWIG extension to Ruby under Windows 95/NT is roughly
similar to the
process used with Unix. Normally, you will want to produce a DLL that
@ -337,7 +306,9 @@ you may need to download the source distribution to the Ruby package,
as you
will need the Ruby header files.
<p><a name="n10"></a></p>
<h3>23.2.1 Running SWIG from Developer Studio</h3>
<a name="n10"></a><H3>23.2.1 Running SWIG from Developer Studio</H3>
If you are developing your application within Microsoft developer
studio, SWIG
can be invoked as a custom build option. The process roughly follows
@ -426,12 +397,16 @@ Foo = 3.0
<p>
</p>
<hr><a name="n11"></a>
<h2>23.3 The Ruby-to-C/C++ Mapping</h2>
<a name="n11"></a><H2>23.3 The Ruby-to-C/C++ Mapping</H2>
This section describes the basics of how SWIG maps C or C++
declarations
in your SWIG interface files to Ruby constructs.
<a name="n12"></a>
<h3>23.3.1 Modules</h3>
<a name="n12"></a><H3>23.3.1 Modules</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Ruby
module. If
you specify:
@ -489,7 +464,9 @@ take care that the names of your constants, classes and methods don't
conflict
with any of Ruby's built-in names.
<a name="n13"></a></p>
<h3>23.3.2 Functions</h3>
<a name="n13"></a><H3>23.3.2 Functions</H3>
Global functions are wrapped as Ruby module methods. For example, given
the SWIG interface file <tt>example.i</tt>:
<p></p>
@ -513,7 +490,9 @@ irb(main):002:0&gt; <b>Example.fact(4)</b>
</pre>
</blockquote>
<a name="n14"></a>
<h3>23.3.3 Variable Linking</h3>
<a name="n14"></a><H3>23.3.3 Variable Linking</H3>
C/C++ global variables are wrapped as a pair of singleton methods for
the
module: one to get the value of the global variable and one to set it.
@ -565,7 +544,9 @@ The <tt>%immutable</tt> directive stays in effect until it is
explicitly
disabled using <tt>%mutable</tt>.
<a name="n15"></a>
<h3>23.3.4 Constants</h3>
<a name="n15"></a><H3>23.3.4 Constants</H3>
C/C++ constants are wrapped as module constants initialized to the
appropriate value. To create a constant, use <tt>#define</tt> or the
<tt>%constant</tt> directive. For example:
@ -584,7 +565,9 @@ irb(main):002:0&gt; <b>Example::PI</b>
</pre>
</blockquote>
<a name="n16"></a>
<h3>23.3.5 Pointers</h3>
<a name="n16"></a><H3>23.3.5 Pointers</H3>
"Opaque" pointers to arbitrary C/C++ types (i.e. types that aren't
explicitly
declared in your SWIG interface file) are wrapped as data objects. So,
@ -605,7 +588,9 @@ internally generated Ruby class:
A <tt>NULL</tt> pointer is always represented by the Ruby <tt>nil</tt>
object.
<a name="n17"></a>
<h3>23.3.6 Structures</h3>
<a name="n17"></a><H3>23.3.6 Structures</H3>
C/C++ structs are wrapped as Ruby classes, with accessor methods (i.e.
"getters"
and "setters") for all of the struct members. For example, this struct
@ -684,7 +669,9 @@ generates accessor functions such as this:
<pre>Foo *Bar_f_get(Bar *b) {<br> return &amp;b-&gt;f;<br>}<br><br>void Bar_f_set(Bar *b, Foo *val) {<br> b-&gt;f = *val;<br>}<br></pre>
</blockquote>
<a name="n18"></a>
<h3>23.3.7 C++ classes</h3>
<a name="n18"></a><H3>23.3.7 C++ classes</H3>
Like structs, C++ classes are wrapped by creating a new Ruby class of
the same
name with accessor methods for the public class member data.
@ -719,7 +706,9 @@ In Ruby, these functions are used as follows:
<pre>require 'Example'<br><br>l = Example::List.new<br><br>l.insert("Ale")<br>l.insert("Stout")<br>l.insert("Lager")<br>Example.print(l)<br>l.length()<br>----- produces the following output <br>Lager<br>Stout<br>Ale<br>3<br></pre>
</blockquote>
<a name="n19"></a>
<h3>23.3.8 C++ Inheritance</h3>
<a name="n19"></a><H3>23.3.8 C++ Inheritance</H3>
The SWIG type-checker is fully aware of C++ inheritance. Therefore, if
you have
classes like this:
@ -831,7 +820,9 @@ and <tt>Base2</tt>
(i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck
Typing"</a>).
<a name="n20"></a>
<h3>23.3.9 C++ Overloaded Functions</h3>
<a name="n20"></a><H3>23.3.9 C++ Overloaded Functions</H3>
C++ overloaded functions, methods, and constructors are mostly
supported by SWIG. For example,
if you have two functions like this:
@ -883,7 +874,9 @@ arises--in this case, the
first declaration takes precedence.
<p>Please refer to the <a href="SWIGPlus.html">"SWIG and C++"</a>
chapter for more information about overloading. <a name="n21"></a></p>
<h3>23.3.10 C++ Operators</h3>
<a name="n21"></a><H3>23.3.10 C++ Operators</H3>
For the most part, overloaded operators are handled automatically by
SWIG
and do not require any special treatment on your part. So if your class
@ -912,7 +905,9 @@ More details about wrapping C++ operators into Ruby operators is
discussed in
the <a href="#n39">section on operator overloading</a>.
<a name="n22"></a>
<h3>23.3.11 C++ namespaces</h3>
<a name="n22"></a><H3>23.3.11 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
the module nor do namespaces result in a module that is broken up into
submodules or packages. For example, if you have a file like this,
@ -946,7 +941,9 @@ 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.
<a name="n23"></a>
<h3>23.3.12 C++ templates</h3>
<a name="n23"></a><H3>23.3.12 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
to create wrappers, you have to tell SWIG to create wrappers for a
particular
@ -1000,7 +997,9 @@ examples.
More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a>
chapter.
<a name="n24"></a>
<h3>23.3.13 C++ Smart Pointers</h3>
<a name="n24"></a><H3>23.3.13 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been
wrapped by
so-called "smart pointers." Generally, this involves the use of a
@ -1036,7 +1035,9 @@ simply use the <tt>__deref__()</tt> method. For example:
<pre>irb(main):004:0&gt; <b>f = p.__deref__()</b> # Returns underlying Foo *<br></pre>
</blockquote>
<a name="n25"></a>
<h3>23.3.14 Cross-Language Polymorphism</h3>
<a name="n25"></a><H3>23.3.14 Cross-Language Polymorphism</H3>
SWIG's Ruby module supports cross-language polymorphism (a.k.a. the
"directors"
feature) similar to that for SWIG's Python module. Rather than
@ -1047,7 +1048,9 @@ secton just notes the differences that you need to be aware of when
using this
feature with Ruby.
<a name="n26"></a>
<h4>23.3.14.1 Exception Unrolling</h4>
<a name="n26"></a><H4>23.3.14.1 Exception Unrolling</H4>
Whenever a C++ director class routes one of its virtual member function
calls to a
Ruby instance method, there's always the possibility that an exception
@ -1070,7 +1073,9 @@ Ruby exception
is raised, it will be caught here and a C++ exception is raised in its
place.
<hr><a name="n27"></a>
<h2>23.4 Input and output parameters</h2>
<a name="n27"></a><H2>23.4 Input and output parameters</H2>
A common problem in some C programs is handling parameters passed as
simple
pointers. For example:
@ -1144,7 +1149,9 @@ In Ruby:
</blockquote>
<hr>
<a name="n28"></a>
<h2>23.5 Simple exception handling </h2>
<a name="n28"></a><H2>23.5 Simple exception handling </H2>
The SWIG <tt>%exception</tt> directive can be used to define a
user-definable
exception handler that can convert C/C++ errors into Ruby exceptions.
@ -1197,7 +1204,9 @@ Ruby exception classes, consult a Ruby reference such as <a
href="http://www.rubycentral.com/book"><em>Programming Ruby</em></a>.
</p>
<hr><a name="n29"></a>
<h2>23.6 Typemaps</h2>
<a name="n29"></a><H2>23.6 Typemaps</H2>
This section describes how you can modify SWIG's default wrapping
behavior
for various C/C++ datatypes using the <tt>%typemap</tt> directive.
@ -1212,7 +1221,9 @@ Typemaps are only used if you want to change some aspect of the
primitive
C-Ruby interface.
<a name="n30"></a></p>
<h3>23.6.1 What is a typemap?</h3>
<a name="n30"></a><H3>23.6.1 What is a typemap?</H3>
A typemap is nothing more than a code generation rule that is attached
to a specific C datatype. For example, to convert integers from Ruby to
C,
@ -1292,7 +1303,9 @@ follows (notice how the length parameter is omitted):
<pre>puts Example.count('o','Hello World')<br>2<br></pre>
</blockquote>
<a name="n31"></a>
<h3>23.6.2 Ruby typemaps</h3>
<a name="n31"></a><H3>23.6.2 Ruby typemaps</H3>
The previous section illustrated an "in" typemap for converting Ruby
objects to
C. A variety of different typemap methods are defined by the Ruby
@ -1348,7 +1361,9 @@ Examples of these typemaps appears in the <a href="#n34">section on
typemap
examples</a>
<a name="n32"></a>
<h3>23.6.3 Typemap variables</h3>
<a name="n32"></a><H3>23.6.3 Typemap variables</H3>
Within a typemap, a number of special variables prefaced with a <tt>$</tt>
may appear. A full list of variables can be found in the "<a
href="Typemaps.html">Typemaps</a>" chapter. This is a list of the most
@ -1390,7 +1405,9 @@ so that their values can be properly assigned.
<blockquote>The Ruby name of the wrapper function being created.
</blockquote>
<a name="n33"></a>
<h3>23.6.4 Useful Functions</h3>
<a name="n33"></a><H3>23.6.4 Useful Functions</H3>
When you write a typemap, you usually have to work directly with Ruby
objects.
The following functions may prove to be useful. (These functions plus
@ -1399,17 +1416,23 @@ more can be found in <a href="http://www.rubycentral.com/book"><em>Programming
Ruby</em></a>, by David Thomas
and Andrew Hunt.)
<p><a name="n34"></a></p>
<h4>23.6.4.1 C Datatypes to Ruby Objects</h4>
<a name="n34"></a><H4>23.6.4.1 C Datatypes to Ruby Objects</H4>
<blockquote>
<pre>INT2NUM(long or int) - int to Fixnum or Bignum<br>INT2FIX(long or int) - int to Fixnum (faster than INT2NUM)<br>CHR2FIX(char) - char to Fixnum<br>rb_str_new2(char*) - char* to String<br>rb_float_new(double) - double to Float<br></pre>
</blockquote>
<a name="n35"></a>
<h4>23.6.4.2 Ruby Objects to C Datatypes</h4>
<a name="n35"></a><H4>23.6.4.2 Ruby Objects to C Datatypes</H4>
<blockquote>
<pre> int NUM2INT(Numeric)<br> int FIX2INT(Numeric)<br> unsigned int NUM2UINT(Numeric)<br> unsigned int FIX2UINT(Numeric)<br> long NUM2LONG(Numeric)<br> long FIX2LONG(Numeric)<br>unsigned long FIX2ULONG(Numeric)<br> char NUM2CHR(Numeric or String)<br> char * STR2CSTR(String)<br> char * rb_str2cstr(String, int*length)<br> double NUM2DBL(Numeric)<br><br></pre>
</blockquote>
<a name="n36"></a>
<h4>23.6.4.3 Macros for VALUE</h4>
<a name="n36"></a><H4>23.6.4.3 Macros for VALUE</H4>
<p>
<tt>RSTRING(str)-&gt;len</tt>
</p>
@ -1423,7 +1446,9 @@ and Andrew Hunt.)
<tt>RARRAY(arr)-&gt;ptr</tt>
<blockquote>pointer to array storage</blockquote>
<a name="n37"></a>
<h4>23.6.4.4 Exceptions</h4>
<a name="n37"></a><H4>23.6.4.4 Exceptions</H4>
<p>
<tt>void rb_raise(VALUE exception, const char *fmt, ...)</tt>
</p>
@ -1480,7 +1505,9 @@ 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>.
</blockquote>
<a name="n38"></a>
<h4>23.6.4.5 Iterators</h4>
<a name="n38"></a><H4>23.6.4.5 Iterators</H4>
<p>
<tt>void rb_iter_break()</tt>
</p>
@ -1512,12 +1539,16 @@ value)</tt>
<blockquote> Equivalent to Ruby's <tt>throw</tt>.
</blockquote>
<a name="n39"></a>
<h3>23.6.5 Typemap Examples</h3>
<a name="n39"></a><H3>23.6.5 Typemap Examples</H3>
This section includes a few examples of typemaps. For more examples,
you
might look at the examples in the <tt>Example/ruby</tt> directory.
<a name="n40"></a>
<h3>23.6.6 Converting a Ruby array to a char **</h3>
<a name="n40"></a><H3>23.6.6 Converting a Ruby array to a char **</H3>
A common problem in many C programs is the processing of command line
arguments, which are usually passed in an array of <tt>NULL</tt>
terminated
@ -1543,7 +1574,9 @@ 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. <a name="n41"></a>
<h3>23.6.7 Collecting arguments in a hash</h3>
<a name="n41"></a><H3>23.6.7 Collecting arguments in a hash</H3>
Ruby's solution to the "keyword arguments" capability of some other
languages is
to allow the programmer to pass in one or more key-value pairs as
@ -1681,7 +1714,9 @@ the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
directory
of the SWIG distribution.
<a name="n42"></a>
<h3>23.6.8 Pointer handling</h3>
<a name="n42"></a><H3>23.6.8 Pointer handling</H3>
Occasionally, it might be necessary to convert pointer values that have
been
stored using the SWIG typed-pointer representation. Since there are
@ -1740,7 +1775,9 @@ typemap variable <tt>$1_descriptor</tt>. For example:
<pre>%typemap(in) Foo * {<br> SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor, 1);<br>}<br></pre>
</blockquote>
<a name="n43"></a>
<h4>23.6.8.1 Ruby Datatype Wrapping</h4>
<a name="n43"></a><H4>23.6.8.1 Ruby Datatype Wrapping</H4>
<p>
<tt>VALUE Data_Wrap_Struct(VALUE class, void (*mark)(void *), void
(*free)(void *), void *ptr)</tt>
@ -1763,7 +1800,9 @@ from the data object
</blockquote>
<hr>
<a name="n44"></a>
<h2>23.7 Operator overloading</h2>
<a name="n44"></a><H2>23.7 Operator overloading</H2>
SWIG allows operator overloading with, by using the <tt>%extend</tt>
or
<tt>%rename</tt> commands in SWIG and the following operator names
@ -1777,7 +1816,9 @@ for defining an equivalence operator, there is no separate method for
handling <i>inequality</i> since Ruby parses the expression <i>a != b</i>
as <i>!(a == b)</i>.
<a name="n45"></a>
<h3>23.7.1 Example: STL Vector to Ruby Array</h3>
<a name="n45"></a><H3>23.7.1 Example: STL Vector to Ruby Array</H3>
<em><b>FIXME: This example is out of place here!</b></em>
<p>Another use for macros and type maps is to create a Ruby array from
a STL
@ -1831,9 +1872,13 @@ types:
%enddef
</blockquote></pre>
<a name="n46"></a>
<h2>23.8 Advanced Topics</h2>
<a name="n46"></a><H2>23.8 Advanced Topics</H2>
<a name="n47"></a>
<h3>23.8.1 Creating Multi-Module Packages</h3>
<a name="n47"></a><H3>23.8.1 Creating Multi-Module Packages</H3>
The chapter on <a href="Advanced.html">Advanced Topics</a> discusses
the basics
of creating multi-module extensions with SWIG, and in particular
@ -1922,7 +1967,9 @@ irb(main):005:0&gt; <b>c.getX()</b>
</pre>
</blockquote>
<a name="n48"></a>
<h3>23.8.2 Defining Aliases</h3>
<a name="n48"></a><H3>23.8.2 Defining Aliases</H3>
It's a fairly common practice in the Ruby built-ins and standard
library to
provide aliases for method names. For example, <em>Array#size</em> is
@ -1966,7 +2013,9 @@ apply (see the chapter on <a href="Customization.html">"Customization
Features"</a>)
for more details).
<a name="n49"></a></p>
<h3>23.8.3 Predicate Methods</h3>
<a name="n49"></a><H3>23.8.3 Predicate Methods</H3>
Predicate methods in Ruby are those which return either <tt>true</tt>
or
<tt>false</tt>. By convention, these methods' names end in a question
@ -2013,7 +2062,9 @@ kinds
of features apply (see the chapter on <a href="Customization.html">"Customization
Features"</a>) for more details).
<a name="n50"></a>
<h3>23.8.4 Specifying Mixin Modules</h3>
<a name="n50"></a><H3>23.8.4 Specifying Mixin Modules</H3>
The Ruby language doesn't support multiple inheritance, but it does
allow you
to mix one or more modules into a class using Ruby's <tt>include</tt>
@ -2062,7 +2113,9 @@ kinds
of features apply (see the chapter on <a href="Customization.html">"Customization
Features"</a>) for more details).
<a name="n51"></a>
<h3>23.8.5 Interacting with Ruby's Garbage Collector</h3>
<a name="n51"></a><H3>23.8.5 Interacting with Ruby's Garbage Collector</H3>
<b>This section is still unfinished!</b>
<p>By default, SWIG ensures that any C++ objects it creates are
destroyed when the