/trunk/Examples/ruby/value/index.html
HTML | 114 lines | 86 code | 28 blank | 0 comment | 0 complexity | 8ecafedc3756985850293e5bb5dff257 MD5 | raw file
1<html> 2<head> 3<title>SWIG:Examples:ruby:value</title> 4</head> 5 6<body bgcolor="#ffffff"> 7 8 9<tt>SWIG/Examples/ruby/value/</tt> 10<hr> 11 12<H2>Passing and Returning Structures by Value</H2> 13 14<p> 15Occasionally, a C program will manipulate structures by value such as shown in the 16following code: 17 18<blockquote> 19<pre> 20/* File : example.c */ 21 22typedef struct Vector { 23 double x, y, z; 24} Vector; 25 26double dot_product(Vector a, Vector b) { 27 return (a.x*b.x + a.y*b.y + a.z*b.z); 28} 29 30Vector vector_add(Vector a, Vector b) { 31 Vector r; 32 r.x = a.x + b.x; 33 r.y = a.y + b.y; 34 r.z = a.z + b.z; 35 return r; 36} 37</pre> 38</blockquote> 39 40Since SWIG only knows how to manage pointers to structures (not their internal 41representation), the following translations are made when wrappers are 42created: 43 44<blockquote> 45<pre> 46double wrap_dot_product(Vector *a, Vector *b) { 47 return dot_product(*a,*b); 48} 49 50Vector *wrap_vector_add(Vector *a, Vector *b) { 51 Vector *r = (Vector *) malloc(sizeof(Vector)); 52 *r = vector_add(*a,*b); 53 return r; 54} 55</pre> 56</blockquote> 57 58The functions are then called using pointers from the scripting language interface. 59It should also be noted that any function that returns a structure by value results 60in an implicit memory allocation. This will be a memory leak unless you take steps 61to free the result (see below). 62 63<h2>The SWIG interface</h2> 64 65Click <a href="example.i">here</a> to see a SWIG interface file that 66wraps these two functions. In this file, there are a few essential features: 67 68<ul> 69<li>A wrapper for the <tt>free()</tt> function is created so that we 70can clean up the return result created by <tt>vector_add()</tt> 71function. 72 73<p> 74<li>The %inline directive is used to create a few helper functions for creating new Vector 75objects and to print out the value (for debugging purposes). 76</ul> 77 78<h2>A Ruby Script</h2> 79 80Click <a href="runme.rb">here</a> to see a script that uses these functions from Ruby. 81 82<h2>Notes</h2> 83 84<ul> 85<li>When the '<tt>-c++</tt>' option is used, the resulting wrapper code for the return value 86changes to the following: 87 88<blockquote> 89<pre> 90Vector *wrap_vector_add(Vector *a, Vector *b) { 91 Vector *r = new Vector(vector_add(*a,*b)); 92 return r; 93} 94</pre> 95</blockquote> 96 97<p> 98<li>If you define C structure (or C++ class with '<tt>-c++</tt>' option) 99in the interface file, the SWIG generated wrappers can automaticallyclean 100up the result of return-by-reference by GC. 101 102<p> 103<li>Passing parameters by value like this really isn't the best C programming style. 104If possible, you might change your application to use pointers. 105 106<p> 107<li>Similar translations are made when C++ references are used. 108 109 110</ul> 111 112<hr> 113</body> 114</html>