Examples/ruby/pointer/index.html - third_party/swig - Git at Google

 <html>
 <head>
 <title>SWIG:Examples:ruby:pointer</title>
 </head>

 <body bgcolor="#ffffff">

 <tt>SWIG/Examples/ruby/pointer/</tt>
 <hr>

 <H2>Simple Pointer Handling</H2>

 <p>
 This example illustrates a couple of techniques for handling
 simple pointers in SWIG.  The prototypical example is a C function
 that operates on pointers such as this:

 <blockquote>
 <pre>
 void add(int *x, int *y, int *r) {
     *r = *x + *y;
 }
 </pre>
 </blockquote>

 By default, SWIG wraps this function exactly as specified and creates
 an interface that expects pointer objects for arguments.  The only
 problem is how does one go about creating these objects from a script?

 <h2>Possible Solutions</h2>

 <ul>
 <li>Write some helper functions to explicitly create objects.  For
 example:

 <blockquote>
 <pre>
 int *new_int(int ivalue) {
   int *i = (int *) malloc(sizeof(ivalue));
   *i = ivalue;
   return i;
 }
 int get_int(int *i) {
   return *i;
 }

 void delete_int(int *i) {
   free(i);
 }
 </pre>
 </blockquote>

 Now, in a script you would do this:

 <blockquote>
 <pre>
 a = new_int(37)
 b = new_int(42)
 c = new_int(0)
 add(a,b,c)
 r = get_int(c)
 print "Result = #{r}\n"
 delete_int(a)
 delete_int(b)
 delete_int(c)
 </pre>
 </blockquote>

 <p>
 <li>Use the SWIG pointer library.  For example, in the interface file
 you would do this:

 <blockquote>
 <pre>
 %include "pointer.i"
 </pre>
 </blockquote>

 and in a script you would do this:

 <blockquote>
 <pre>
 a = ptrcreate("int",37)
 b = ptrcreate("int",42)
 c = ptrcreate("int")
 add(a,b,c)
 r = ptrvalue(c)
 print "Result = #{r}\n"
 ptrfree(a)
 ptrfree(b)
 ptrfree(c)
 </pre>
 </blockquote>

 The advantage to using the pointer library is that it unifies some of the helper
 functions behind a common set of names.  For example, the same set of functions work
 with int, double, float, and other fundamental types.

 <p>
 <li>Use the SWIG typemap library.  This library allows you to completely
 change the way arguments are processed by SWIG.  For example:

 <blockquote>
 <pre>
 %include "typemaps.i"
 void add(int *INPUT, int *INPUT, int *OUTPUT);
 </pre>
 </blockquote>

 And in a script:

 <blockquote>
 <pre>
 r = add(37,42)
 print "Result = #{r}\n"
 </pre>
 </blockquote>
 Needless to say, this is substantially easier.

 <p>
 <li>A final alternative is to use the typemaps library in combination
 with the %apply directive.  This allows you to change the names of parameters
 that behave as input or output parameters. For example:

 <blockquote>
 <pre>
 %include "typemaps.i"
 %apply int *INPUT {int *x, int *y};
 %apply int *OUTPUT {int *r};

 void add(int *x, int *y, int *r);
 void sub(int *x, int *y, int *r);
 void mul(int *x, int *y, int *r);
 ... etc ...
 </pre>
 </blockquote>

 </ul>

 <h2>Example</h2>

 The following example illustrates the use of these features for pointer
 extraction.

 <ul>
 <li> <a href="example.c">example.c</a>  (C Source)
 <li> <a href="example.i">example.i</a>  (Swig interface)
 <li> <a href="runme.rb">runme.rb</a> (Ruby Script)
 </ul>

 <h2>Notes</h2>

 <ul>
 <li>Since pointers are used for so many different things (arrays, output values,
 etc...) the complexity of pointer handling can be as complicated as you want to
 make it.

 <p>
 <li>More documentation on the typemaps.i and pointer.i library files can be
 found in the SWIG user manual.  The files also contain documentation.

 <p>
 <li>The pointer.i library is designed primarily for convenience.  If you
 are concerned about performance, you probably want to use a different
 approach.

 </ul>

 <hr>
 </body>
 </html>
	<html>
	<head>
	<title>SWIG:Examples:ruby:pointer</title>
	</head>

	<body bgcolor="#ffffff">

	<tt>SWIG/Examples/ruby/pointer/</tt>
	<hr>

	<H2>Simple Pointer Handling</H2>

	<p>
	This example illustrates a couple of techniques for handling
	simple pointers in SWIG. The prototypical example is a C function
	that operates on pointers such as this:

	<blockquote>
	<pre>
	void add(int x, int y, int *r) {
	r = x + *y;
	}
	</pre>
	</blockquote>

	By default, SWIG wraps this function exactly as specified and creates
	an interface that expects pointer objects for arguments. The only
	problem is how does one go about creating these objects from a script?

	<h2>Possible Solutions</h2>

	<ul>
	<li>Write some helper functions to explicitly create objects. For
	example:

	<blockquote>
	<pre>
	int *new_int(int ivalue) {
	int i = (int ) malloc(sizeof(ivalue));
	*i = ivalue;
	return i;
	}
	int get_int(int *i) {
	return *i;
	}

	void delete_int(int *i) {
	free(i);
	}
	</pre>
	</blockquote>

	Now, in a script you would do this:

	<blockquote>
	<pre>
	a = new_int(37)
	b = new_int(42)
	c = new_int(0)
	add(a,b,c)
	r = get_int(c)
	print "Result = #{r}\n"
	delete_int(a)
	delete_int(b)
	delete_int(c)
	</pre>
	</blockquote>

	<p>
	<li>Use the SWIG pointer library. For example, in the interface file
	you would do this:

	<blockquote>
	<pre>
	%include "pointer.i"
	</pre>
	</blockquote>

	and in a script you would do this:

	<blockquote>
	<pre>
	a = ptrcreate("int",37)
	b = ptrcreate("int",42)
	c = ptrcreate("int")
	add(a,b,c)
	r = ptrvalue(c)
	print "Result = #{r}\n"
	ptrfree(a)
	ptrfree(b)
	ptrfree(c)
	</pre>
	</blockquote>

	The advantage to using the pointer library is that it unifies some of the helper
	functions behind a common set of names. For example, the same set of functions work
	with int, double, float, and other fundamental types.

	<p>
	<li>Use the SWIG typemap library. This library allows you to completely
	change the way arguments are processed by SWIG. For example:

	<blockquote>
	<pre>
	%include "typemaps.i"
	void add(int INPUT, int INPUT, int *OUTPUT);
	</pre>
	</blockquote>

	And in a script:

	<blockquote>
	<pre>
	r = add(37,42)
	print "Result = #{r}\n"
	</pre>
	</blockquote>
	Needless to say, this is substantially easier.

	<p>
	<li>A final alternative is to use the typemaps library in combination
	with the %apply directive. This allows you to change the names of parameters
	that behave as input or output parameters. For example:

	<blockquote>
	<pre>
	%include "typemaps.i"
	%apply int INPUT {int x, int *y};
	%apply int OUTPUT {int r};

	void add(int x, int y, int *r);
	void sub(int x, int y, int *r);
	void mul(int x, int y, int *r);
	... etc ...
	</pre>
	</blockquote>

	</ul>

	<h2>Example</h2>

	The following example illustrates the use of these features for pointer
	extraction.

	<ul>
	<li> <a href="example.c">example.c</a> (C Source)
	<li> <a href="example.i">example.i</a> (Swig interface)
	<li> <a href="runme.rb">runme.rb</a> (Ruby Script)
	</ul>

	<h2>Notes</h2>

	<ul>
	<li>Since pointers are used for so many different things (arrays, output values,
	etc...) the complexity of pointer handling can be as complicated as you want to
	make it.

	<p>
	<li>More documentation on the typemaps.i and pointer.i library files can be
	found in the SWIG user manual. The files also contain documentation.

	<p>
	<li>The pointer.i library is designed primarily for convenience. If you
	are concerned about performance, you probably want to use a different
	approach.

	</ul>

	<hr>
	</body>
	</html>