diff options
Diffstat (limited to 'Doc/Manual/Ruby.html')
| -rw-r--r-- | Doc/Manual/Ruby.html | 224 |
1 files changed, 121 insertions, 103 deletions
diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index 3cfd1292c..852c7ce58 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -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,10 +149,10 @@ <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. +<p> SWIG 4.2 is known to work with Ruby versions 2.0 and later. Given the choice, you should use the latest stable version of Ruby. You should also determine if your system supports shared libraries and dynamic loading. SWIG will work with or without dynamic loading, but @@ -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> <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 @@ -615,7 +615,25 @@ directive. For example: </p> effect until it is explicitly disabled using <tt>%mutable</tt>. </p> -<H3><a name="Ruby_nn15">34.3.4 Constants</a></H3> +<p>Note: When SWIG is invoked with the <tt>-globalmodule</tt> option in +effect, the C/C++ global variables will be translated into Ruby global +variables. Type-checking and the optional read-only characteristic are +available in the same way as described above. However the example would +then have to be modified and executed in the following way: + +<div class="code targetlang"> +<pre>$ <b>irb</b> +irb(main):001:0> <b>require 'Example'</b> +true +irb(main):002:0> <b>$variable1 = 2</b> +2 +irb(main):003:0> <b>$Variable2 = 4 * 10.3</b> +41.2 +irb(main):004:0> <b>$Variable2</b> +41.2</pre> +</div> + +<H3><a name="Ruby_nn15">35.3.4 Constants</a></H3> <p> C/C++ constants are wrapped as module constants initialized @@ -643,7 +661,7 @@ irb(main):002:0> <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 @@ -667,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 @@ -772,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 @@ -827,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. @@ -980,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 @@ -1070,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 @@ -1112,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 @@ -1169,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, @@ -1211,7 +1229,7 @@ irb(main):004:0> <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 @@ -1304,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 @@ -1365,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 @@ -1448,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> @@ -1462,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 @@ -1527,7 +1545,7 @@ method. For example: </p> <pre>irb(main):004:0> <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 @@ -1536,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 @@ -1559,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 @@ -1597,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 @@ -1667,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 @@ -1689,7 +1707,7 @@ For example: </p> <div class="code"> <pre>%rename("is_it_safe?") is_it_safe(); -%typemap(out) int is_it_safe "$result = ($1 != 0) ? Qtrue : Qfalse;"; +%typemap(out) int is_it_safe "$result = ($1 != 0) ? Qtrue : Qfalse;" int is_it_safe();</pre> </div> @@ -1716,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 @@ -1748,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 @@ -1783,7 +1801,7 @@ irb(main):003:0> <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 @@ -1922,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 @@ -2034,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 @@ -2101,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 @@ -2258,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> @@ -2295,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 @@ -2310,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 @@ -2467,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 @@ -2513,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> @@ -2555,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 @@ -2580,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, @@ -2651,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 @@ -2724,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 @@ -2746,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 @@ -2797,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 @@ -2812,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 @@ -2837,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 @@ -2852,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. @@ -2906,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 @@ -2933,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> @@ -2957,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 @@ -2975,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++ @@ -3030,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 @@ -3089,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 @@ -3162,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 @@ -3220,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> @@ -3282,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 @@ -3297,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"> @@ -3339,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 @@ -3393,7 +3411,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt> </tr> <tr> <td>char * StringValuePtr(String)</td> - <td>SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)</td> + <td>SWIG_AsCharPtrAndSize(VALUE, char**, size_t*, int* alloc)</td> </tr> <tr> <td>char * rb_str2cstr(String, int*length)</td> @@ -3407,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> @@ -3430,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, @@ -3509,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> @@ -3555,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 @@ -3627,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 @@ -3841,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 @@ -3900,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 @@ -3927,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 @@ -4019,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> @@ -4053,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> @@ -4083,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, @@ -4104,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> @@ -4128,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> @@ -4148,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> @@ -4160,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> @@ -4181,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> @@ -4197,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> @@ -4208,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> @@ -4392,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 @@ -4518,7 +4536,7 @@ irb(main):005:0> <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 @@ -4585,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 @@ -4608,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 @@ -4639,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 @@ -4784,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 @@ -5010,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 @@ -5139,7 +5157,7 @@ irb(main):016:0></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 @@ -5307,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 |