From 3ff8d1e629dce7c0002179c66f59becd8e5620c0 Mon Sep 17 00:00:00 2001 From: Charlie Savage Date: Thu, 2 Feb 2006 10:57:37 +0000 Subject: [PATCH] Significant rearrangment of some sections of the documentaiton. Also added additional information about exception handling and getter/setter methods. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@8677 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/Manual/Ruby.html | 393 ++++++++++++++++++++++++------------------- 1 file changed, 221 insertions(+), 172 deletions(-) diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index 30cb1ae0a..6e8e65aac 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -47,48 +47,50 @@
  • Defining Aliases
  • Predicate Methods
  • Bang Methods +
  • Getters and Setters
  • Input and output parameters -
  • Simple exception handling -
  • Typemaps +
  • Exception handling -
  • Operator overloading +
  • What is a typemap? +
  • Ruby typemaps +
  • Typemap variables +
  • Useful Functions -
  • Advanced Topics +
  • Typemap Examples +
  • Converting a Ruby array to a char ** +
  • Collecting arguments in a hash +
  • Pointer handling -
  • Memory Management +
  • Example: STL Vector to Ruby Array + +
  • Advanced Topics +
  • Memory Management + @@ -989,18 +991,18 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 
    class MyArray {
    public:
     // Construct an empty array
     MyArray();
     
     // Return the size of this array
     size_t length() const;
    };

    %extend MyArray {
     // MyArray#size is an alias for MyArray#length
     size_t size() const {
     return self->length();
     }
    }
    -
    +

    A better solution is to use the %alias directive (unique to SWIG's Ruby module). The previous example could then be rewritten as: 

    // MyArray#size is an alias for MyArray#length
    %alias MyArray::length "size";

    class MyArray {
    public:
     // Construct an empty array
     MyArray();
     
     // Return the size of this array
     size_t length() const;
    };
    -
    +

    Multiple aliases can be associated with a method by providing a comma-separated list of aliases to the %alias directive, e.g. 

    %alias MyArray::length "amount,quantity,size";
    -
    +

    From an end-user's standpoint, there's no functional difference between these two approaches; i.e. they should get the same result from calling either MyArray#size or MyArray#length. However, when the %alias directive is used, SWIG doesn't need to generate all of the wrapper code that's usually @@ -1020,19 +1022,19 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 

    %rename("is_it_safe?") is_it_safe();

    %typemap(out) int is_it_safe 
     "$result = ($1 != 0) ? Qtrue : Qfalse;";

    int is_it_safe();
    -
    +

    A better solution is to use the %predicate directive (unique to SWIG's Ruby module) to designate a method as a predicate method. For the previous example, this would look like: 

    %predicate is_it_safe();

    int is_it_safe();
    -
    +

    This method would be invoked from Ruby code like this:

    irb(main):001:0> Example::is_it_safe?
    true
    -
    +

    The %predicate directive is implemented using SWIG's "features" mechanism and so the same name matching rules used for other kinds of features apply (see the chapter on "Customization @@ -1055,6 +1057,35 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ "features" mechanism and so the same name matching rules used for other kinds of features apply (see the chapter on     "Customization Features") for more details).

    +

    30.4.4 Getters and Setters

    + + +

    Often times a C++ library will expose properties through getter and setter methods. For example:

    +
    + 
    class Foo {
+	Foo() {}
+
+ int getValue() { return value_; }
+
+ void setValue(int value) { value_ = value; }
+
+private:
+ int value_;
+};
    +
    +

    By default, SWIG will expose these methods to Ruby as get_value and set_value. However, it more natural for these methods to be exposed in Ruby as value and value=. That allows the methods to be used like this:

    +
    + 
    irb(main):001:0> foo = Foo.new()
+irb(main):002:0> foo.value = 5
+irb(main):003:0> puts foo.value
    +
    +

    This can be done by using the %rename directive:

    +
    + 
    %rename("value") Foo::getValue();
+%rename("value=") Foo::setValue(int value);
+
    +
    +

     

    30.5 Input and output parameters

    @@ -1134,17 +1165,22 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 
    r, c = Example.get_dimensions(m)
    -

    30.6 Simple exception handling

    +

    30.6 Exception handling

    -

    - The SWIG %exception directive can be used to define a user-definable +

    30.6.1 Using the %exception directive

    + + +

    The SWIG %exception directive can be used to define a user-definable exception handler that can convert C/C++ errors into Ruby exceptions. The chapter on Customization Features contains more details, but suppose you have a C++ class like the following :

    - 
    class DoubleArray {
     private:
     int n;
     double *ptr;
     public:
     // Create a new array of fixed size
     DoubleArray(int size) {
     ptr = new double[size];
     n = size;
     }
     // Destroy an array
     ~DoubleArray() {
     delete ptr;
     }
     // Return the length of the array
     int length() {
     return n;
     }

     // Get an array item and perform bounds checking.
     double getitem(int i) {
     if ((i >= 0) && (i < n))
     return ptr[i];
     else
     throw RangeError();
     }
     // Set an array item and perform bounds checking.
     void setitem(int i, double val) {
     if ((i >= 0) && (i < n))
     ptr[i] = val;
     else {
     throw RangeError();
     }
     }
     };
    + 
    class DoubleArray {
     private:
       int n;
       double *ptr;
     public:
       // Create a new array of fixed size
       DoubleArray(int size) {
         ptr = new double[size];
         n = size;
       }
+
       // Destroy an array
       ~DoubleArray() {
         delete ptr;
       }  
+
       // Return the length of the array
       int length() {
         return n;
       }

       // Get an array item and perform bounds checking.
       double getitem(int i) {
         if ((i >= 0) && (i < n))
           return ptr[i];
         else
           throw RangeError();
       }
+
       // Set an array item and perform bounds checking.
       void setitem(int i, double val) {
         if ((i >= 0) && (i < n))
           ptr[i] = val;
         else {
           throw RangeError();
         }
       }
     };

    Since several methods in this class can throw an exception for an out-of-bounds @@ -1152,7 +1188,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ following in an interface file:

    - 
    %exception {
     try {
     $action
     }
     catch (const RangeError&) {
     static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
     rb_raise(cpperror, "Range error.");
     }
    }

    class DoubleArray {
     ...
    };
    + 
    %exception {
     try {
       $action
     }
     catch (const RangeError&) {
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
       rb_raise(cpperror, "Range error.");
     }
    }

    class DoubleArray {
     ...
    };

    The exception handling code is inserted directly into generated wrapper @@ -1165,7 +1201,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ handler to only apply to specific methods like this:

    - 
    %exception getitem {
     try {
     $action
     }
     catch (const RangeError&) {
     static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
     rb_raise(cpperror, "Range error in getitem.");
     }
    }

    %exception setitem {
     try {
     $action
     }
     catch (const RangeError&) {
     static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
     rb_raise(cpperror, "Range error in setitem.");
     }
    }
    + 
    %exception getitem {
     try {
       $action
     }
     catch (const RangeError&) {
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
       rb_raise(cpperror, "Range error in getitem.");
     }
    }

    %exception setitem {
     try {
       $action
     }
     catch (const RangeError&) {
       static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
       rb_raise(cpperror, "Range error in setitem.");
     }
    }

    In this case, the exception handler is only attached to methods and functions @@ -1175,14 +1211,103 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ exception handling. See the chapter on Customization Features for more examples.

    -

    When raising a Ruby exception from C/C++, use the rb_raise() function - as shown above. The first argument passed to rb_raise() is the - exception type. You can raise a custom exception type (like the cpperror - example shown above) or one of the built-in Ruby exception types. For a list of - the standard Ruby exception classes, consult a Ruby reference such as - Programming Ruby. -

    -

    30.7 Typemaps

    +

    30.6.2 Raising exceptions

    + + +

    There are three ways to raise exceptions from C++ code to Ruby.

    +

    The first way is to use SWIG_exception(int code, const char *msg). The following table shows the mappings from SWIG error codes to Ruby exceptions:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    SWIG_MemoryErrorrb_eNoMemError
    SWIG_IOErrorrb_eIOError
    SWIG_RuntimeErrorrb_eRuntimeError
    SWIG_IndexErrorrb_eIndexError
    SWIG_TypeErrorrb_eTypeError
    SWIG_DivisionByZerorb_eZeroDivError
    SWIG_OverflowErrorrb_eRangeError
    SWIG_SyntaxErrorrb_eSyntaxError
    SWIG_ValueErrorrb_eArgError
    SWIG_SystemErrorrb_eFatal
    SWIG_AttributeErrorrb_eRuntimeError
    SWIG_NullReferenceErrorrb_eNullReferenceError*
    SWIG_ObjectPreviouslyDeletedErrorrb_eObjectPreviouslyDeleted*
    SWIG_UnknownErrorrb_eRuntimeError
    * These error classes are created by SWIG and are not built-in Ruby exception classes
    +

    The second way to raise errors is to use SWIG_Raise(obj, type, desc). Obj is a C++ instance of an exception class, type is a string specifying the type of exception (for example, "MyError") and desc is the SWIG description of the exception class. For example:

    +

    %raise(SWIG_NewPointerObj(e, SWIGTYPE_p_AssertionFailedException, 0), ":AssertionFailedException", SWIGTYPE_p_AssertionFailedException);

    +

    This is useful when you want to pass the current exception object directly to Ruby, particularly when the object is an instance of class marked as an %exceptionclass (see the next section for more information).

    +

    Last, you can raise an exception by directly calling Ruby's C api. This is done by invoking the rb_raise() function. The first argument passed to rb_raise() is the + exception type. You can raise a custom exception type or one of the built-in Ruby exception types.

    +

    30.6.3 Exception classes

    + + +

    Starting with SWIG 1.3.28, the Ruby module supports the %exceptionclass directive, which is used to identify C++ classes that are used as exceptions. Classes that are marked with the %exceptionclass directive are exposed in Ruby as child classes of rb_eRuntimeError. This alows C++ exceptions to be directly mapped to Ruby exceptions, providing for a more natural integration between C++ code and Ruby code.

    +
    + 
    	%exceptionclass CustomError;
+		
+	%inline %{
+	 	class CustomError { };
+	
+		class Foo { 
    	   public:
    		 	void test() { throw CustomError; }
+	  };
+	}
+
    +
    +

    From Ruby you can now call this method like this: +

    + 
    foo = Foo.new
+begin
+  foo.test()
+rescue CustomError => e
+  puts "Caught custom error"
+end
    +
    +

    For another example look at swig/Examples/ruby/exception_class.
    +

    30.7 Typemaps

    @@ -1195,7 +1320,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 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.

    -

    30.7.1 What is a typemap?

    +

    30.7.1 What is a typemap?

    @@ -1262,7 +1387,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 

    puts Example.count('o','Hello World')
    2
    -

    30.7.2 Ruby typemaps

    +

    30.7.2 Ruby typemaps

    @@ -1319,7 +1444,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ Examples of these typemaps appears in the section on typemap examples

    -

    30.7.3 Typemap variables

    +

    30.7.3 Typemap variables

    Within a typemap, a number of special variables prefaced with a $ may @@ -1355,7 +1480,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/

    $symname

    The Ruby name of the wrapper function being created.
    -

    30.7.4 Useful Functions

    +

    30.7.4 Useful Functions

    @@ -1365,19 +1490,19 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ by David Thomas and Andrew Hunt.)

     

    -

    30.7.4.1 C Datatypes to Ruby Objects

    +

    30.7.4.1 C Datatypes to Ruby Objects

    INT2NUM(long or int) - int to Fixnum or Bignum
    INT2FIX(long or int) - int to Fixnum (faster than INT2NUM)
    CHR2FIX(char) - char to Fixnum
    rb_str_new2(char*) - char* to String
    rb_float_new(double) - double to Float
    -

    30.7.4.2 Ruby Objects to C Datatypes

    +

    30.7.4.2 Ruby Objects to C Datatypes

     int NUM2INT(Numeric)
     int FIX2INT(Numeric)
     unsigned int NUM2UINT(Numeric)
     unsigned int FIX2UINT(Numeric)
     long NUM2LONG(Numeric)
     long FIX2LONG(Numeric)
    unsigned long FIX2ULONG(Numeric)
     char NUM2CHR(Numeric or String)
     char * STR2CSTR(String)
     char * rb_str2cstr(String, int*length)
     double NUM2DBL(Numeric)

    -

    30.7.4.3 Macros for VALUE

    +

    30.7.4.3 Macros for VALUE

    @@ -1392,7 +1517,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/

    capacity of the Ruby array

    RARRAY(arr)->ptr

    pointer to array storage
    -

    30.7.4.4 Exceptions

    +

    30.7.4.4 Exceptions

    @@ -1459,7 +1584,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ with the -w flag. The given format string fmt and remaining arguments are interpreted as with printf(). -

    30.7.4.5 Iterators

    +

    30.7.4.5 Iterators

    @@ -1498,14 +1623,14 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/

    Equivalent to Ruby's throw.
    -

    30.7.5 Typemap Examples

    +

    30.7.5 Typemap Examples

    This section includes a few examples of typemaps. For more examples, you might look at the examples in the Example/ruby directory.

    -

    30.7.6 Converting a Ruby array to a char **

    +

    30.7.6 Converting a Ruby array to a char **

    @@ -1529,7 +1654,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 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.

    -

    30.7.7 Collecting arguments in a hash

    +

    30.7.7 Collecting arguments in a hash

    @@ -1642,7 +1767,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ the extension, can be found in the Examples/ruby/hashargs directory of the SWIG distribution.

    -

    30.7.8 Pointer handling

    +

    30.7.8 Pointer handling

    @@ -1689,7 +1814,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 

    %typemap(in) Foo * {
     SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);
    }
    -

    30.7.8.1 Ruby Datatype Wrapping

    +

    30.7.8.1 Ruby Datatype Wrapping

    @@ -1710,34 +1835,17 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/

    Retrieves the original C pointer of type c-type from the data object obj and assigns that pointer to ptr.
    -

    30.8 Operator overloading

    +

    30.7.9 Example: STL Vector to Ruby Array

    -

    - SWIG allows operator overloading with, by using the %extend or %rename - commands in SWIG and the following operator names (derived from Python): -

    -
    - 
     General 
    __repr__ - inspect
    __str__ - to_s
    __cmp__ - <=>
    __hash__ - hash
    __nonzero__ - nonzero?

     Callable 
    __call__ - call

     Collection 
    __len__ - length
    __getitem__ - []
    __setitem__ - []=

     Numeric 
    __add__ - +
    __sub__ - -
    __mul__ - *
    __div__ - /
    __mod__ - %
    __divmod__ - divmod
    __pow__ - **
    __lshift__ - <<
    __rshift__ - >>
    __and__ - &
    __xor__ - ^
    __or__ - |
    __neg__ - -@
    __pos__ - +@
    __abs__ - abs
    __invert__ - ~
    __int__ - to_i
    __float__ - to_f
    __coerce__ - coerce

    Additions in 1.3.13  
    __lt__ - < 
    __le__ - <=
    __eq__ - ==
    __gt__ - >
    __ge__ - >=

    -
    -

    - Note that although SWIG supports the __eq__ magic method name for - defining an equivalence operator, there is no separate method for handling inequality - since Ruby parses the expression a != b as !(a == b). -

    -

    30.8.1 Example: STL Vector to Ruby Array

    - - -

    - FIXME: This example is out of place here! -

    -

    Another use for macros and type maps is to create a Ruby array from a STL vector +

    FIXME: This example is out of place here!

    +

    Another use for macros and type maps is to create a Ruby array from a STL vector of pointers. In essence, copy of all the pointers in the vector into a Ruby array. The use of the macro is to make the typemap so generic that any vector with pointers can use the type map. The following is an example of how to construct this type of macro/typemap and should give insight into constructing similar typemaps for other STL structures: -

    + 

    %define PTR_VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)
    %typemap(out) vectorclassname &, const vectorclassname & {
     VALUE arr = rb_ary_new2($1->size());
     vectorclassname::iterator i = $1->begin(), iend = $1->end();
     for ( ; i!=iend; i++ )
     rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));
     $result = arr;
    }
    %typemap(out) vectorclassname, const vectorclassname {
     VALUE arr = rb_ary_new2($1.size());
     vectorclassname::iterator i = $1.begin(), iend = $1.end();
     for ( ; i!=iend; i++ )
     rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));
     $result = arr;
    }
    %enddef
    @@ -1762,18 +1870,34 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 
    %define VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)
    %typemap(out) vectorclassname &, const vectorclassname & {
     VALUE arr = rb_ary_new2($1->size()); 
     vectorclassname::iterator i = $1->begin(), iend = $1->end();
     for ( ; i!=iend; i++ )
     rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));
     $result = arr;
    }
    %typemap(out) vectorclassname, const vectorclassname {
     VALUE arr = rb_ary_new2($1.size()); 
     vectorclassname::iterator i = $1.begin(), iend = $1.end();
     for ( ; i!=iend; i++ )
     rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));
     $result = arr;
    }
    %enddef
    -

    30.9 Advanced Topics

    + +

    30.8 Advanced Topics

    -

    30.9.1 Creating Multi-Module Packages

    +

    30.8.1 Operator overloading

    +

    + SWIG allows operator overloading with, by using the %extend or %rename + commands in SWIG and the following operator names (derived from Python): +

    +
    + 
     General 
    __repr__ - inspect
    __str__ - to_s
    __cmp__ - <=>
    __hash__ - hash
    __nonzero__ - nonzero?

     Callable 
    __call__ - call

     Collection 
    __len__ - length
    __getitem__ - []
    __setitem__ - []=

     Numeric 
    __add__ - +
    __sub__ - -
    __mul__ - *
    __div__ - /
    __mod__ - %
    __divmod__ - divmod
    __pow__ - **
    __lshift__ - <<
    __rshift__ - >>
    __and__ - &
    __xor__ - ^
    __or__ - |
    __neg__ - -@
    __pos__ - +@
    __abs__ - abs
    __invert__ - ~
    __int__ - to_i
    __float__ - to_f
    __coerce__ - coerce

    Additions in 1.3.13  
    __lt__ - < 
    __le__ - <=
    __eq__ - ==
    __gt__ - >
    __ge__ - >=

    +

    + Note that although SWIG supports the __eq__ magic method name for + defining an equivalence operator, there is no separate method for handling inequality + since Ruby parses the expression a != b as !(a == b). +

    +

    30.8.2 Creating Multi-Module Packages

    + + +

    The chapter on Working with Modules discusses the basics of creating multi-module extensions with SWIG, and in particular the considerations for sharing runtime type information among the different modules. -

    +

    As an example, consider one module's interface file (shape.i) that defines our base class:

    @@ -1836,83 +1960,8 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 
    $ irb
    irb(main):001:0> require 'shape'
    true
    irb(main):002:0> require 'circle'
    true
    irb(main):003:0> c = Circle::Circle.new(5, 5, 20)
    #<Circle::Circle:0xa097208>
    irb(main):004:0> c.kind_of? Shape::Shape
    true
    irb(main):005:0> c.getX()
    5.0
    -

    30.9.2 Defining Aliases

    - -

    - It's a fairly common practice in the Ruby built-ins and standard library to - provide aliases for method names. For example, Array#size is an alias - for Array#length. If you'd like to provide an alias for one of your - class' instance methods, one approach is to use SWIG's %extend directive - to add a new method of the aliased name that calls the original function. For - example: -

    -
    - 
    class MyArray {
    public:
     // Construct an empty array
     MyArray();
     
     // Return the size of this array
     size_t length() const;
    };

    %extend MyArray {
     // MyArray#size is an alias for MyArray#length
     size_t size() const {
     return self->length();
     }
    }
    -
    -

    - A better solution is to instead use the %alias directive (unique to - SWIG's Ruby module). The previous example could then be rewritten as: -

    -
    - 
    // MyArray#size is an alias for MyArray#length
    %alias MyArray::length "size";

    class MyArray {
    public:
     // Construct an empty array
     MyArray();
     
     // Return the size of this array
     size_t length() const;
    };
    -
    -

    - Multiple aliases can be associated with a method by providing a comma-separated - list of aliases to the %alias directive, e.g. -

    -
    - 
    %alias MyArray::length "amount,quantity,size";
    -
    -

    - From an end-user's standpoint, there's no functional difference between these - two approaches; i.e. they should get the same result from calling either MyArray#size - or MyArray#length. However, when the %alias directive is - used, SWIG doesn't need to generate all of the wrapper code that's usually - associated with added methods like our MyArray::size() example. -

    -

    Note that the %alias directive is implemented using SWIG's "features" - mechanism and so the same name matching rules used for other kinds of features - apply (see the chapter on "Customization - Features") for more details).

    -

    30.9.3 Predicate Methods

    - - -

    - Predicate methods in Ruby are those which return either true or false. - By convention, these methods' names end in a question mark; some examples from - built-in Ruby classes include Array#empty? (which returns true - for an array containing no elements) and Object#instance_of? (which - returns true if the object is an instance of the specified class). For - consistency with Ruby conventions you would also want your interface's - predicate methods' names to end in a question mark and return true or false. -

    -

    One cumbersome solution to this problem is to rename the method (using SWIG's %rename - directive) and provide a custom typemap that converts the function's actual - return type to Ruby's true or false. For example: -

    -
    - 
    %rename("is_it_safe?") is_it_safe();

    %typemap(out) int is_it_safe 
     "$result = ($1 != 0) ? Qtrue : Qfalse;";

    int is_it_safe();
    -
    -

    - A better solution is to instead use the %predicate directive (unique - to SWIG's Ruby module) to designate certain methods as predicate methods. For - the previous example, this would look like: -

    -
    - 
    %predicate is_it_safe();

    int is_it_safe();
    -
    -

    and to use this method from your Ruby code:

    -
    - 
    irb(main):001:0> Example::is_it_safe?
    true
    -
    -

    - Note that the %predicate directive is implemented using SWIG's - "features" mechanism and so the same name matching rules used for other kinds - of features apply (see the chapter on "Customization - Features") for more details). -

    -

    30.9.4 Specifying Mixin Modules

    +

    30.8.3 Specifying Mixin Modules

    @@ -1953,7 +2002,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ apply (see the chapter on "Customization Features") for more details).

    -

    30.10 Memory Management

    +

    30.9 Memory Management

    One of the most common issues in generating SWIG bindings for Ruby is proper @@ -1972,7 +2021,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ 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.

    -

    30.10.1 Mark and Sweep Garbage Collector

    +

    30.9.1 Mark and Sweep Garbage Collector

    Ruby uses a mark and sweep garbage collector. When the garbage collector runs, @@ -1998,7 +2047,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ allocated in creating the underlying C struct or C++ struct, then a "free" function must be defined that deallocates this memory.

    -

    30.10.2 Object Ownership

    +

    30.9.2 Object Ownership

    As described above, memory management depends on clearly defining who is @@ -2073,7 +2122,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/

    This code can be seen in swig/examples/ruby/tracking.


    -

    30.10.3 Object Tracking

    +

    30.9.3 Object Tracking

    The remaining parts of this section will use the class library shown below to @@ -2142,7 +2191,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/ implement your own free functions (see below) you may also have to call theSWIG_RubyRemoveTracking and RubyUnlinkObjects methods.

    -

    30.10.4 Mark Functions

    +

    30.9.4 Mark Functions

    With a bit more testing, we see that our class library still has problems. For @@ -2184,7 +2233,7 @@ $ ruby -e 'puts $:.join("\n")'
    /usr/local/lib/ruby/site_ruby/1.6 /usr/

    This code can be seen in swig/examples/ruby/mark_function.

    -

    30.10.5 Free Functions

    +

    30.9.5 Free Functions

    By default, SWIG creates a "free" function that is called when a Ruby object is